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'c^ L User Guide ^meT^l^■^r^.^^^)f!.^^^■• >...^»vi!r 
1. Introduction . . . . 



1.1. Introduction & Legal Stuff 



The part of this manual is a general introduction to DrawTools. It isn't a tutorial on computer graphics, although 
some basic topics are discussed. For more in depth information on specific tools, consult the reference section. 

We'd love to hear from you. If you have any questions, comments, or complaints, please feel free to write to 
Pegasoft at* *^ ttysf^ltj^ a*ov *>?f4- ^t-. j my\ . i-j :- v : •■ . 

/a Bfjf -«cisfi i^sVi :ofi lliy^ Vf&t h:'> ^ 1^ > j • . .1 
■'a rXgA^ i: t-;ei?> gJ^fttJs l^ps^'^i i :*sit. ■ \; 
^i*5>5 JilW BO'^ :'/ttj^T9S> iei<>;>( s.-^-'SiiM * 



Pegasoft 

Honsberger Avenue, R. R. #1 



Jordan Station, Ontario, Canada 
LOR ISO 



This manual and the related software contained on the diskettes are copyrighted materials. All rights reserved. Duplication 
of any of the above described materials, for other than personal use of the purchaser, without express written permission of 
Pegasoft of Canada is a violation of the copyright law of the United States and Canada, and is subject to both civil and 
criminal prosecution. 

Pegasoft and DrawTools are trademarks of Pegasoft of Canada. ^ H^.'^W i^n^ At siool'^^aiCf ^^.■^iJ'?^- X'-'^X" "■: 



1.2. What is DrawTools? 



Welcome to DrawTools, a collection of over 100 useful graphics and animation tools for the IIGS. The first version 
was released as shareware around the fall of 1990. Since then, it has significantly grown, with new features and 
more versatility. 

Feel free to distribute the TOOL098 file with any programs you make, but if you wish to distribute any other 
files on the DrawTools disks, please get prior permission from Pegasoft. 

1.3. System Requirements 

XX i^ivcA gfS«3^' ; . 

DrawTools 3.1 requires the following: ■ jf iJs^^.M'i K ; ^ 

\ , . . , .flbrfSfe-O ^■.-< 

An Apple IIGS with system software 5.0.2 and at least 9K free RAM in bank 0. ^ fcsrx^ix^ i v s 
To use DrawTools, the following toolsets must be active: Tool Locator, Misc. Tools, Memory Manager, 
QuickDraw II. 



1.4. Installation 



1 . Copy the TOOU)98 file to the Tools folder of your startup disk. (This is DrawTools.) , 

2. Copy the DT.Drivers folder (the folder and its cont«its) to the System: Tools folder of your startup disk. 

3. Copy the icon file to your Icons folder. 

The DrawTools disks also contain the following: vCCV?* .setis^i^si^-sw^ ^ i !>ji.-.v> - ■ 

a. PicEd 3.0, a sin:^le editor for picture libraries 

b. Lib.Converter 1.2, a utility wfiich franslates a screen template into a picture library. The foldw 
includes some sample templates. ^ ,t 

c. Demo. Game, a small assembly language game that demonstrate some of the animation tools 
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d. l)emo.Sysl6, a demo program written in Micol Advanced Basic 4.2 

e. sample programs for a wide variety of computer languages 

1.5. Using DrawTools with ... ^ 

Complete/TML Pascal U - an interface file written in TML Pascal II is included on the disk in the TML.Pascal 
folder. Copy the object file to the folder containing the interface files for the other toolsets, include DrawTools in 
your USES list at the beginning of your program. non.-^^ari ^t,^^ « '^m^ i. ■ ■ : 

Micol Advanced BASIC - You need to use the TOOLBOX command. A set of aliases are supplied for users with 
the latest version of BASIC: you can copy these into your program or you can use the INCLUDE command. Each 
alias requires a space after the tool name. 



E 



DrawShadow will not work unless you are nmning a stand-alone application. There are also some tools 
that require a Pascal string (not a BASIC string): a length (byte) followed by the text of the string. You 
cannot use these tools directly: you will either have to construct a string with POKEs, or use Micol Macro. 
All the toolsets that DrawTools requires are started for you when you use HGR or HGR2. 

Merlin 16-^ - a macro file (Draw.Macs.S) is included on the disk. Copy it into your MACRO.LIBRARY 
subdirectory, and USE it in your source files. gtj ^ v. M^tfi^ :o fw^aiifxv ?, »i c» S'- ■ 

ORCA/Pascal - an interface file (Drawtools.int) is inclu^ on the disk. Copy this file into OrcaPascalDefs. In 
your program, include DrawTools in your USES list. m^mte^ i - «» issriitinj ^. f - h'i^- ■■ -«.■ 

ORCA/M - A macro file (ml6.DrawTooIs) is included on the disk. Copy this file into your ainclude folder. Use it 
like any other macro file. 

ORC A/C - There are no interface files available: you can use DrawTools if you use the necessary tool definitions. 
DrawTools will not work with Prizm. » ■ s^JOC'"^' - " ;:tm^ib ttJ &*f: ■ ' 



Pe g asus Pagcal - Follow the ORCA/Pascal directions. 



Example: Starting DrawTools 3.1. 

Pegasus Pascal: Start it like any other toolset .^m^ikt'siiim:--^^. ■ r k^i 

Uses Coninon, . . . , DraWTools 

I start required tools, ca: use StartGraphice iiifrw ?r>;; riqs.:-*- ■■ - 

LoadOneTool 98, 

DPHandle = NGi*«andle{256, MylD, $C005, 0) 
DP = ord( DPHandle- ) 
DrawStartUp DP, MylD 
Kxt«ndBu£f sra 



Load DrawTools .. .., 

allocate direct page space ., j^, , 
convert to an integer 
start DrawTbole 



if using a lot of pixies 



ORCA/Pascal: Start it like any other toolset ^ ^ ^^^^wCi^a 

Uses Cctnmon, .... DrawTools; - 
^ start required tools, or use StartGraphice } 

LoadOneTool (98, 0); ( Load DrawTools } 

DPHandle 1= Nev*Iandle(2B6, MylD, $C005, 0); { allocate direct page space } 

DP != ord( DPHandle' ); { ccaivert to an integer } 

Drawatart0p( DP, MylD ); 'vtVi''^ 9 itAth^ { start DraWTools } 'i^' « 

E3Ct«ndBu££«ra; { if using a lot of pixies } .-'.i--: 
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BASIC: Use the following commands: Q 

REM Start required tools, or use HGR/HGR2. 

TOOLBOXd, 15: 98, 0) : REM Tool Locator's LoadOneTool 



DrawTools_Handle = 256 : REM Allocate direct page space 
DrawTool s_Addr ess = 

POKE 202, 1 3»jl^»iw^r?.fKJil'^^*;?fi*-;^3 
Get_Mem( DrawTool B_Handle, DrawTool s^flddreeB) 'E-fCLy^K."? W .""'u -v-^'.!^ 

Addreee% = INT (DrawTools_Addrese) f REM Convert to an integeam -Wf^ *i vtijiifi- 

MylDft = Peek(238) ^ Peek(239) * 256 ^JjfejW!^ «Kil ml ^^rfxpSOa * k \ 

TOOLBOXf -Draws tartUp : AddreB6%, MyID%) ■ ^s»u<f !W£^y JaJ! t^'^qn, 

REM Without aliases; TOOLB0X( 98, 3 : flddress%, MyID% ) 
TOOIjBOX{ -ExtandBuf fere 



: REM If using a lot of pixiea . ^ .^^^^ 



Merlin 16+: Start it like any other toolset 

USE 4: Draw. Macs 
-•LoadOne^R>ol #98;#0 
-Nevtfiandle #$100;MyID;#$C005;#0 
PLA 

PuBhWord MylD ^ 
Draws tar tUp 
Ext*ndBu£f are 



ail m>^'' 



if using a lot of pixies 



ORCA/M: Start it like any other toolset 

MCOPY mie.DrawToole 

pli2 #99 ; load DrawToole 

ph2 #0 

__LoadOneTool 

ph4 #0 

ph4 #$100 

ph2 My ID ;■ ■ 

ph2 #$C005 

ph4 #0 _ ^ - • ^' 

_NewHandle 
pha 

ph2 lytylD 
_D r awS t ar t TTp 
Ext«ndBu££«r0 



a. 



^ .t 



r 



Examples: Stopping E>rawTools 3.1. 
Pegasus Pascal: 

I DrawShutDown 

ORCA/Pascal: 

j DrawShutDown; 



> 

; if uaing a lot of pixiee : 



BASIC: 

TOOLBOX (-DrawShutDown ) 

REM Without aliases: TOOLBOX(98, 



Merlin 16+: 

DrawShutDown 



3) 



ORCA/M: 



Dr awShu tDown 
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2. Graphics on the IIGS ^-^5 



■.K-l-- 



2.1. A Brief Introduction 



-■MM*, 



■-f Hid*:' 

.-■.^..'-'■J-./r 



Graphics is the art of drawing with a coiiq>iiter. In the IIGS, tha^ is a special toolset dedicated to drawing called 
"QuickDraw ir, or QuickDraw for short. QuickDraw provides all the basic drawing functions for the average 
application: it draws tines, rectangles, ovals, text, cursors and many other things you see on the screeo. It's 
impossible to make a complete list of the QuickDraw tools here since there are well over 200; consult the Apple 
IIGS Toolbox Reference or any book introducing IIGS programming for more information. 



BASIC : WhenevCT you use HCOLOR, HPLOT, or the other BASIC commands, BASIC uses QuickDraw. 



Before discussing tlw details of DrawTotrfs, you should know a little bit of how pictures are displayed on die 
IIGS screen. We will be discussing 320 mode to keep things simple. The super high-resolution graphics screen is 
located in baiJc $E1 of memory. Each dot on tiie sciera, or "pixel", consists of half a byte of memory , or 4 bits. 
This means up to sixteen colours can normally be displayed on the screen. The screen consists of 320 pixels 
horizontally and 200 pixels vertically. These pixels are locirted in the area $E12000 to $E19CFF of memory. 

The next 200 bytes, starting at $E19D00, are for the Scanline Control Bytes, or SCB's, one for each line on the 
st^eeai. The SCB's determine the attributes for that line: 

bit 0...3 - the palette of the line (0 to 15) j&?,toOS lesdX/ m SfS^r! J; Ti^^ ■ 

bit 4 - zero - . - , • , ^ 

bit 5 - 1 if fill mode is active. With fill mode active, colour (usually black) behaves differently. 
If you draw an area of the screen in colour 0, it will appear in the same colour as the area of the 
screen to the immediat e left. Hie colour is "pulled" across the black areas of the screoi, filling 
them in. 

bit 6 - 1 will cause an SCB interrupt on this line 
bit 7 - 1 for 640 resolution; for 320 resolution 



us 



The memory located fit>m $E19E00 to $E19FFF contains the 16 colour palettes (or "color tables"). Each 
palette contains 16 integer RGB values that describe the 16 colours you can see on the screen. Quickl^aw only uses 
palette (see Figure 1). Palettes and RGB colc»ir words are discussed more below. ■ 



Figure 1 : The QuickDraw II colou rs fin 320 mode^ 
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This whole section of nttmory, from $E12000 to $E19FFF, can be "shadowed" from $012000 to $0I9FFF in 
bank 1. This area is called Uie shadow screen. You can use the shadow screen if you set bit 15 in the Master SCB 
■whea you start QuickDraw up. When the shadow screen is in use, drawing takes place much faster than usual. In 
addition, the shadow screen can be made invisible (with DrawTools ShadowOft) so diat QuickDraw & DrawTools 
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draw many times faster than without shadowing, but the pictures will remain hidden until use DrawToois' 
QuickWipe. 

2,2 Working with Colour ^^.^ oj ^^h.^ tuoiftiw ^-'.p^-^'-^ -a ^A.^f/.- . •.' - 

On the IIGS, the super hires screen can display 16 colours at a time with a single palette. You can change the 
current drawing colour using QuickE>raw's SetSolidPenl^t(c) or BASIC'S HCOLOR=c. The hue and brightness of 
each colour is described by an RGB colour word, a combination of red, green and blue components. Each 
component can be in a range from to 15. For example, black is 0,0,0; white is 15,15,15; bright red is 15,0,0; 
orange is 15,7,0. 

E)rawTools has a tool called SetColour that will take the red, green and blue components and give you the 

corresponding RGB value. .-^.^ ■:. ...7,....-*.. . , 

' ' 3S3J 07 f>Sx> aa-i^ Y.*f»fi'5t>: 4ar#*. ysi^iif;. 

Example : Creating the colour "orange" with SetColour. ii ^sH" a^Vm^ » «i tss ^s^jisffo *^ va ;- 'it^ 
Pascal: RGBCoIout t-^ fl«tColour{15, 7, Q); *!.^Vfw«<! rj; ^SV-frA'^*?.'.^^ .v^;': 

BASIC: TOOLBOX{ -SetColour : 0, 15, 7, 0; RGBColour% ) 

REM Include at start for RGBColour%l Add cne for each result value.. -.ij -.[i^-. 

Example : You can use QuickDraw's SetCoIorEntry to change a default colour: i ; ^vc^fc*^:^*^ t «c- 
PaSCal: SetColorEtitry( 0, 5, SetColour{ 15, 7, ) ); i.iie^' L>*q-^- 

BASIC: TOOLBOX( -SetColour i 0, 15, 7, 0; RGBColour% ) «asa i—; '■^'■••■v- 

TOOLBOXC 4, 16: 0, 0, RGBColour* ) i ; P tj^r 

Besides SetColour, there is a SetColPercent will do the same thing, accept you use percentages (0...100) of 
red, green and bhie components instead of values from 0...15. FadeColour will make an RGB value darker or 
brighter. BlendColour will blend to colours together to make a new colour. FindColour will find the closest 
colour in a palette to the colour word you specify. 

Although QuickDraw uses one palette, the lIGS can actually display colours from 16 different palettes at one 
time. Each line must have only one palette. DrawToois has a tool called SetPalette that will change the palette 
for a set of lines. , >*>v,. , 

ExaiQp le: Changing the top half of the screen (lines 0—99) to palette 1. , .j= . -(.asiHiwfta t- '■'f:o^K*C7:- 

Pascal: s«tp«i«tt«( o, 99, 1); $ . ' fii:. 

BASIC: TooLBcix{~fl«tp«i«tt» 1 0, 99, 1) 

Now anything you draw on the top half of the screen will appear in the colours of palette 1 instead of palette 0. 
You can set the colours of any of the palettes using SetColor&itry( palette, colour, RGBvalue); or in BASIC, 
TOOLBGX( 4, 16: paJette%, colour%, RGBvalue% ). 

FadePal will make make all the colours in a palette darker. UnfadePal will make all the colours in a palette 
brighter. A more powerful version of FindColour is FindPalette Give FindPalette a palette of colours, and it 
will try to match ttiem up to colours in the current palette. This tool is useful for NDAs; you can never be sure 
which colours are on the screen if an NDA is running under a paint program. FindPalette can tell you if the colours 
have changed, and to what. 

Example: See the reference for more details. If you want to find the closest colours on the screen to the standard 320 
palette: 

Define the colours array:0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15 ^ ^wia *^tje> ,.>a • 

Define the Palette:$000, $777, $841, $72C $78F, $CCC, $FFF 

After the call is made, the values in colour list will change to reflect the actual numbers for these colours on the 
current screen (or the closest colours them). ' ■ -ae* — -h --. .x-. 
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2.3 Fades, Wipes, and Dissolves 



What set of tools would be complete without some way to gracefully change from one scene to another? There 
are four basic ways to make such a transition. The simplest way is to erase the screen and draw a new picture; it's 
easy, effective, but it lacks a certain class, especially on a computer with the possiblities of the IIGS. A common 
way to switch pictures is with a fade. A fade changes all the colours to a single colour, and then reverses the process 
to reveal a new picture. While the colours are identical, any drawing you do is invisible. DrawTools provides two 
fades: (1) QuickFade, the standard fede used in so many qjplications, which dims all the colours in the first eight 
palettes to black; (2) IncrFade, which fades out everything except the red component, and then fades to black 

A second method of switching pictures is with a wipe. A wipe copies a picture from shadow screen onto the 
screen in a special order. DrawTools provides two wipes which copy the shadow screen to the main scre«i: (1) 
QuickWipe, which instantly copies one to the other, and (2) VBWipe which copies using a Vencian blind effect. 

The last way to change screens is a dissolve. This is a special kind of wipe which operates on a pixel -by-pixel 
basis. There are no dissolves in DrawTools. , : , . . i - -( - 

Example : How to fade to black, draw something new, and unfade to reveal it. a '"^ c t=b'.-- -: &sy 

Pascal: 



QuiokFadaOutd) ; 
repeat until Fad«Don«; 
{draw the new screen here} 
QuiokFadalnd) ; 
repeat until FKd*Don«; 



BASIC: 

TOOLBOX(-QuiokF«d«Out i 1) 

REPEAT 

„ , TOOLBOX{-Fmd»Don« : 0; FadeDone%) 
UHTIL FadeDone% <> 
REM Draw the new screen here 



/ ^tto ^sfu ^i<I".i f-'v ''^W' -'----: 

t ,*«B9^ «eO ST'tfUrT. la-'-': ■..■-s ' r-' 



TOOLBOX { - Qui ckF ad«Zn 

REPEflT 

TOOLBOX { ~ F ad aDon • 
UNTIL FadeDoneft <> 

Merlin 16+: 

-QulakFadaOut #1 
QFOLoop -F mdaDon a 
PLA 

BEQ QPOLocp ->■- 
, * Draw new screen here 

-QulokFadaXn #1 
QFILoop -FadaDona 
PLA 

BEQ QFILocp 



1) 



; FadeDone%) 



] 



A^'JVl 7» >i i >ii ^» ?.?i' >-' ■ v 



Example : How to use the Venician Blind wipe tool to wipe a new screen over an old one. 

Pascal: ^ , . 

{make sure the shadow ecreen is allocated} .O-ViJ^-j; ?r.^:. -. -Ai -.. ■- 

DrawShadow; ^ . ^ '^'^ -i^^^^ ^ u- ' I^-^ 

;>dl9p2 ShadovOffi; ' ' ei^4?r UiW i.aJ Tiao?')ti 

{draw the new screen here} ' * ass^' .^'^i*;-; V.sff^'i ^ tif*>.: . v^.-^ r' , 
VBWlpa; 
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DrawMaln; { or ShadowOn, if you want to use the shadow ecreen } 



BASIC: Reminder: Uses the shadow screen; stand-alone programs onlyl 
TOOLBOX ("Drawehadow ) 
TOOLBOX ("ShadowOff ) - - l 

REM CJraw new screen here 
TOOLBOX(~VBWipa ) 
TOOLBOX (-DrawMain ) 



Merlin 16+ 

DravSbadow 

_ShadowOf f 

;draw the new ecreen here 
VBWlpa 
DrawHain 
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3. Animation i^' > v"t» 



3.1 What is Animation? ^ 

Aninuiticm is die illusion of motion created when, a sequ^ce of pictures is rapidly displayed. Each picture, 
called a cell or frame, is a modified version of the picture before it. When each of these still frames is displayed 
quickly, one after another, they give the illusicm of smooth motion. A movie di^Iays 24 frames per second, and at 
60 or beytmd the eye can't distinguish animation from real motion. Reasonable conq>uter animation can be achieved 
at speeds of even 4 frames per second. 

To show a flag being raised, you would first start with a picture of flag pole. Thai you would create a series of 
pictures, each with the flag a little farther up the pole. The final picture would be drawn with the flag at die top of 
the pole. Each of these pictures of the flag and the flag pole is a frame. When you display these pictures rapidly and 
in order, the flag appears to smoothly rise up the pole. This is the fiindamental principle of animation. _ 

3.2 Animation Examples: Dialog Ideas . - . 

To view some sample animation sequences, start PicEd and load the dialog.pics picture hbrary included in die 
PicEd folder. This file is an unpacked picture hbrary created from the Dlog Jdeas320 file using the Library Converter 
utility. Once the file is loaded, try some of the following animation sequences. .--c.,^^; 



l.NoteAlert 0,1,2,3,3,3,255,0 hit; .4 ..^*'•- 
2. Caution Alert 4,5,6,7,6,5,255,0 '—^ -iw* 3 Jl ^ 

3. Stop Alert 8,9.10,11^55,0 si-^ j^:^ S i - - 

4. Working GS 12,13,14,12,13,14,12,13,14.i5,15.15,255»0 : «^ -M^L'-t^^i^. t-^ 

5. Swap Disks 16,17,18,19,20^1^^3,255,0 ■ : cxJ«S-^i9^ ..r- 

To try one of these animations: *^ 

1. Click on ttu! ani button. , 

2. Click on the seq button. . ; , ^j,^^^,,.,^. ■ 

3. Type in the picture sequeaKe, one number at a time. ^ <.;.t.^iwi u 

4. Click on the Go! button. 

5. Type in the speed nund)ffl-. - ^ i > 't 

6. To stop the playback, hold down the mouse button. tgi. .#s j:jr i v. .-, 

Try some experimeiUs. wWim r^.» ->'^- * 

3.3 Colour Cycling ..-z^io 1-^:^10 ,d r.>if>.- 

One of the simplest methods of performing animation is colour cycling. It is the process of changing RGB 
colour words to make objects on the screen appear and disappear. Most paint programs for the IIGS have some kind 
of colour cycling feature. 

To use colour cycling, you draw only ood picture, but you paint differoit frames in dilfCTent colours. With the 
flag pole example, you could draw a series of flags up the flag pole, each in a different colour, the lowest flag in 
colour 1, the second lowest in colour 2, and so on. When you are finished, you have a flag pole fiill of coloured 
flags (see Figure 2). If you change all of the colours except colour 1 to black, the only flag that is visible is the one 
on the bottom of the flag pole. If you change w^our 1 to black, and change colour 2 to the colour of the flag, the 
second flag on the flag pole appears. By cychng through the current palette, making one colour after another visible. 
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the flag appears to rise up the pole. 



1 



Fi gure 2: Flagpole Example 



Colour 12 3 4 



To do colour cycling in the cuirent palette, all you need are two QuickDraw tools: GetColorEntry and 
SetColorEntry. The first gives you the RGB colour word for a particular palette entry. The second lets you change 
a colour iu a specified position in a palette to a new colour. There is also a GetColorTabie and SetColorTable that 
lets you change whole palettes at a time. Here's an example of how you might write the flag animation: 



Example: Colour Cycling of a flag pole with five flags. 

Pascal: 

procedure AnimateFlagPole; 

var OldCoioure i ColorTable; 

FlagCoIour, Last FlagCol our, i t integer? 
begin 

GetColorTabie (0, OldColours) ; { save the original coloure ) Sfif iffl3fc-:' 
LastFlagColour t= 5;( uBed to erase old flags } lif^. ! 

for i := 1 to 5 do SetCoiorEntry(0, i, $000) ; { erase all the flags } -^.l-^v 
for i 1= 1 to 100 do beginC one hundred times } -tfi fUfiJ' 't > 

for FlagColour t= 1 to 5 do begin { for each flag colour } 

SetColorEntry (0, LastFlagColour, $000) ; { Make the last flag invisible } 
SetColorEntry {0, FlagColour, $FFF) ; { draw the flag in white } 
LastFlagColcRor i= FlagColour;! this flag gets erased next } 
end; 

end; ' 
SetColorTable(0, OldColours) ; { restore original colours } 
end {ftnimateFlagPole} t 



BASIC: 

DIM 01dColoure%(15) 



PROC AnimateFlagPole 

01dColoursL% = P£DR[ 01dColoura%( ) : REM Get address of array 
01dColoursH% =PEEK{202) 

TOOLBOX { 4, 15 : 0, 01dColourBH%, OldColourBL% ) : REM Save colours in the array 



Last FlagColour % = 5 
FOR i% = 1 TO 5 

TO0LB0X( 4, 16: 0, i%, ) 
NEXT i% 

FOR i% = 1 TO 100 

FOR FlagColour% = 1 TO 5 

TOOLBOX ( 4, 16: 0, LastFlagColour%, 0) 
TOOLBOX( 4, 16: 0, FlagColour%, 4095) 
Last FlagColour % = FlagColour% 
NEXT FlagColaur% 
NEXT i% . . 



REM Used to erase old flags 
REM Erase all the flags 



rju safe 3D 9t:_mttk> TiMfr, r-^J: 



REW One hundred times " ^' 

REM For each flag colour " ' *' 
REM Make the last flag invisible 
REM Draw the flag in white 
REM this flag gets erased next "i ■'. 
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TOOLBOX (4, 14 i 0, 01dColoursH% , 01dColoursL%) s REM Restore original colours 
ENDPROC - . L...' .. 

You can do even more impressive colour cycling by changing an entire palette at a time. This is used by many 
video games to create animation across the whole screen without having to do a lot of work. For example, the 
pixels for water may never be redrawn. Water looks like it's moving because the colours of the water pixels are 
slowly changing. This is an impressive animation effect that take very little effort on the part of a program. 

DrawToois provides two tools for palettes that work like GetColorEntry and SetColorEntry. GetPalette gives 

you the palette being used tor a particular line on the screen. SetPalette, which we have seen before, lets you change 

the current palette over a range of lines. ; t-— - " . - - 

■ 1 m^l-} OS •riip^-'i ■:>s-^ ^>-. -o- - : ; - 

Exa^k: Palette Cyclmg. , _ j^a- ' 

Pascal: - ., » v»taft^ ^^m^:^■■f .t'wsia^ --^r. ^ .-i;. i -■ ^-^- .m .. 

procedure CyclePalettee; 

var OldPalette, PalNum, Delay, i ; integer; >■ , .:- . 

begin , 
OldPalette := G«tPal«tt« (1) ; { save the original palette nijmber } 
for i t= 1 to 100 do begin{ one hundred timee 1 

for PalNum j= to 15 do begin { change the screen palette } - i ^ - " 

S«tP«l«tt«{0, 199, PalNum) ; ( to ©ach of the 16 palettes J ^ ' 

for delay t= 1 to 5 do H«ltVB; { time delay = 1/6 second } ' ' ' . 

end; 
end; 

S«tP«l«tt«(0, 199, OldPalette) ; { restore the original palette } 



end {CyciePalettesj ; 



BASIC: ^ i, ■;jT ; 

PROC CyclePalettes 

'roOLBOX(-G«tP«l«tt« I 0, 1 ; OldPalette%) t REM save the original palette 
FOR i% = 1 TO 100 . , 

FOR PalNuin% = TO 15 i REM change the screen palette .s..).sr.)e,,a>77 

TOOIiBOX(-S«tP«l«tt« tO, 199, PalNum%) Sy&L^Sv rr^,.< 

FOR delay* = 1 TO 5 . ._i , j-v,-;,; 

TO0LBOXC~H«itVB ) : REM time delay = 1/6 second - '\ ,.^,,^5 

NEXT delay% ^, j,..^.,.. . - 

NEXT PalNum% 
NEXT i% 

TOOLBOX;-fl»tP«l«tt« lO, 199, 01dPalette%) j REM restore the original palette 

EWDPROC 

3.4 The Art of Animation: Draw, Erase and Redraw 

Colour cycling is fine for some kinds of animation, but a program often needs to save many of the colours in 
the palette for other uses. The more conventional approach to animation is to draw an object on the screm, erase it, 
and then draw it again somewhere else. This cycle of draw, erase, draw, erase, is the tectmique used in most 
computer games. 

The one problem with draw/erase/redraw animation is flicker. This occurs when the object being animated can't 
be redrawn fast enough. The eye sees the picture when it's there and when it isn't there, and tliis makes the object 
you're animating appear to flicker. One of the easiest ways of reducing flicker is to use DrawToois' Wait VB tool 
before you try to ens& anything. . V, , 

Example : The following procedure moves a white box across the screen by drawing it, erasing it, ami then redrawing 

:Wr= i«i>v ^jii^ t^^fs. .^'rv. - :. 
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it. WaitV B is used to keep the flicker !ow. To see the box flicker, try replacing the WaitVB loop with "for delay := 
I to 5000 do and change the numb^ of iterations. 

procedure MoveABox? &i^/e. ii^ .rjf^JTrja n!;ftiJ?*i3< jtf»'=^> .- --a'-o. - 

var Box : rect; i, delay t integer;' ' r-s'-v-,* ?*<4fc*' (f'Wfii^. >i r^r^-wi J^fe^' ^ "'jf 

begin :ss^:m i^Mimfmfii «* <^ dT - ' 

SetRect ( Box, 0, 10, 30, 40) ; { the 30 x 30 box o^^^ ;^jvr,-;, <>- . 

r SetSolidPenPat { 15 ) ; { the box colour } .-siyra/i^; -^1 ail-i) . u-.-- - -.m - ' 

SetSolidBackPat ( the erasing colour } R^.rjjM-;' ^>SeTt a v.-/-^ ^.ti^-'-'i r -^ jr.^ 

for i 1= 1 to 20 do begin! 20 times } 

OffBetRect( Box, 10, 0) ; { move the box 10 pixels to the right 1 

PainCRect( Box ) ; { draw it } ""' ' ' 

for delay := 1 to 5 do WaitVB; {time delay = 1/6 eeccnd ) . 

{ we juBt finished a WaltVBl ] 
EraaeRGct ( Box ) ; { eraee the box without flicker ) 
end; ,' 

end; 

DIM Bax%(e) « Ra! Space for a rectangle . , . , . ^a-^t- 

• • " , ■ _,{. 

PROC MoveflBox , „ 

RSM I'm assuming BoxH% & BoxL% is the address of the box% array. ^ 

TOOIiBOX( 4, 74 i BoxH%, BoxL%, 0, 10, 30, 40) i ?m create a 30 x 30 box 

HCOIOR =15 

BKCOL^ = 

FOR i% = 1 TO 20 I Ra4 20 times 

TOOLBOX(4, 75 : BoxH%, BoxL%, 10, 0) : REM move the box 10 pixels to the right 
T00LB0X{4, 84 t BoxH%, BoxL%) t REM draw it 
FOR delay% = 1 TO 5 

TOOLBOX(-lf«ltVB ) 1 Rai time delay = 1/6 seccnd " 
NEXT delay% 

T0OLBOX{4, 85 i BoxH*, BoxL% )> RQI eraee the box without flickeri 



END i% 

ENDPROC 



3.5 Bit-Mapped Pictures 



Each time QuickDraw paints an object on the screen (like our box) it has to do a number of things: 

a) Make sure the mouse anow i&n't erased. 

b) Make sure the object is actually on the screen. 

c) Make sure the object is within the clipping & visible regions of the currait window or grafjxwt. 



i ^ d) Calculate which colours to use with the pen pattern and pen mask. 



e) Compute which pixels to change in the current pen oKtde & size. 

All this is wiiat makes QuickDraw so handy and powerful, but it also makes it slow, too slow except for the 
simplest kinds of animation. After all, if we are drawing a space ship, we don't need special pen modes, sizes, 
patterns and the rest of those features. To draw a picture very quickly, DrawTools provides a special set of tools call 
the drawing tools. There are 8 drawing tools: Draw, Draw48, DrawAt, Draw48At DrawOn, Draw480n, 
DrawOnAt and Draw480DAt, The basic tool. Draw, draws a bit-mapped picture hbrary pictaire (24 pixels wide 
and 24 pixels high, the ones used with PicEd and the Library Converter). The other tools are variations on Draw: 
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the **48" tools draw 4 pictures at once (like you see in the double-sized window in PicEd); the "At" tools let you 
specify the screen position to draw at; and the "On" tools let you draw matted pictures. We'll talk more about 
pictures and mattes later. Because each of these tools is customised for a particular size and "pen mode", they draw 
pictmes many times faster than QuickDraw can. 

Before we can use the drawing tools, we need to load a pictuire library from a disk with the LoadLibrary tool. 
A picture library is a set of 32 bit-mapped pictures created with PicEd or the Library Converter utility. LoadLibrary 
loads picture library from a disk and it gives you an "ID code" that you can use later on to refer to the library. 
LoadLibrary has some special paramet^ that will be described later on when we talk about matting. There is also 
an UnloadLibrary tool, but you normally don't need to use it. 

You can only draw with one library at a time. To specify which library we want to draw with, we need to use 
the SetLibrary tool. There is also a GetLibrary tool that returns the ID code for the current library. 



LoadLibrary uses a GS/OS string for the pattmame: there is no direct way in BASIC to use GS/OS strings. 
We can take the LoadUbrary/SetLibrary calls with BLOAD. This only works with unpacked libraries. 



Exampit: Loading a library in BASIC without LoadLibrary or SetLibrary. •»■;, • ■ 

BASIC: 

REM DrawToole_Addr% ia the direct page space you allocated vhen you started DraWToole. 
DrawToole^Buf fer = PEEK (DraWrools_Addr%-^4) + PEEK{DraWrools_Addr%+5) * 256 s-..,,:^, - 
POKE 202,0 ! REM In BASIC 5.0, we what to load the whole librairy 1:*-^; y. ;-, 

BLOAD "path name of picture library", DraWrools_Buf f er, 9216 61; CFT '■ - ■=* 

Example : The following procedure demonstrates how to load and display the pictures in an (unpacked) library. The 
LoadLibrary tool requires a GS/OS string (a two-byte length followed by the string itself), so refer to your particular 
language on how to define a GS/OS string. 

Pascal: - ' 

procedure DumpOutLibrary ( pathname i GSOSString) ; ' ,. 

var TheLibrary i integer; { ID code for the library } t- 

begin 

TheLibrary Lo«dLibr«ry( pathname, 0, 0) ; { load the library frctn disk } 
S«tLibr*ry( TheLibrary ) ;{ use this library to draw with ) .* ^ " 

for y j= to 3 do ( 4 rows } ' 

for X 1= to 7 do i 8 pictures per row } alcXJ i" ''ft'" 

TS^a Dr«wAt{ X * 32, y * 32, X + y * 8 ) ; { draw picture # x+8y ) ;.- 

end; ^u^.., ^.-^^^ ^-.jf*- .■:iif-*t;?v'--S't' . 

- II rj&b» <•■'■ Yi;;-*i, '-^i 

BASIC: .Xc- .-riCfjU 9^ '^ftli^Seti'T'- 

PROC DumpOutLibrary ' -.f^^^ 

REM Fake the LoadLibrary/SetLibrary ae described above (or use Micol Macro & LINK) ..^ 
.rsm FOR y% = TO 3 : REM 4 rows ^^^^ j/, , I 

FOR x% = TO 7 . REM e pictures per row ^ ^ ^ ^^^^^ ^^^^ ^ _ . 

- ■ ScreenX% = x% * 32 ' . ^ , 

■ • Scre€nY% = y% * 32 

PicNum% = x% + y% * 8 ■ . 
^ - TOOLBOX (-DrawAt : Scre€nX%, ScreenY%, PicNum% ) 

NEXT x% - «lt ii-a4s^3i# ; 

NEXT y% ■ " ■ 

SRrSNDPROC ■^'!^■ fex??'rmHH !:ri«srs: SStf; jj^^^ 

Example : You can animate pictures with the drawing tools in the same way that we animated the box. If you create 
a picture of a box using PicEd in picture of a library, and you leave picture 1 of the library blank (to erase with), 
then you can animate this box using the following procedure. 
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Pasc&l: '^^> 5f^-»fSi--"''; ct>^'"';- V' . ■. 

procedure MoveBoxInADraWToolBLibrary ( pathname t GSOSString) ; '^css^r*^ .v.j-:? '-V- . / 

ccaiBt Box = 0; { box is picture zero } .a^'v*s-.',t-lioiijP"''^ste M^^-^ ■^f:-^',- ■ <- 

Blank - 1; i blank picture is picture 1 J.. ; (s!k1-w gin^i^ilii .'?dl iift. 

var i, delay : integer; BoxLib : integer; 'e^r-~i s-wr^t-s*" fWK».^li«'-tM ?!> Jr<^ 
begin ;jcj'^ -t?tc 'Ij - 

BoxLib != LoadLibr«ry( pathname, 0, 0) ; { load the pictures ,)^^^ br»-» -fi r-i ■•■ ■-n- 
B.tHbr.ry( BoxLib ),i draw with thie eet } _^ .^^^^ ^-^^ ^^l-.^^J-.t::' . 
for i t= 1 to 28 do begin{ 28 times } . . ' . ' , 

DrawAt{ i * 10, 20, Box) ; { draw a box } * ^ _ .... 

for delay := 1 to 5 do W«itVB;(time delay = 1/6 second } -".r ■ 

DrmwAtC i * 10, 20, Blank) ; { erase the box } 
.xSiW^ end; ^'^-^ t** ^ ^-^ ^J-^\> ^ Kosri ■ftA'^*!..:;;^; ' 'y^--'\ 

BASIC: .^«wh. tiaa x- Sfta^^awxJmirMfcn* .= -«-.;^f' ; ^.'irV- . -i^^^'jv - 

PROC MoveBoxInADrawToolsLibrary 

Blank% = 1 "^"^ * t»*"#^h^_,«i<jfyiW'Y'J',«S3» - -.i^zv^k- : *;'^-:a^t. 

REM Load and set the library ' ' ' ^ *^ Cfi;^. '' j?-.- 'f'-'S - 

TOR i% = 1 TO 2fi ,*rM^U ic rf' ■■■ 

x% = i% * 10 

t-' .... TOOLBOX (~Dr«irAt : x%, 20, Box*) . ., ■%rf^*o5or5 Sfir^-t^^^it ""sdr .';..>-:> 

ifllcramsq ■»* for deiay% = i to 5 ^cP^ 'K^^^O t rnmpa ^-^-^ '--ytv' 

TOOLBOX (-WaitVB ) _ .^^iTJy ?0'-." " -■■'M t^^ i^j^^ - ■ - 

NEXT delay% 

TOOLBOX {-DrawAt : x%, 20, Blank%) .jj^^j, 

3.6 Caching with Library Buffers 

1 

DrawTools provides a caching mechanism that can reduce the swapping time when you change from one library 
to another with SetUbrary. If you need the extra speed that caching provides, use the ExtendBuffers tool after 
DrawStartUp. Now each time you use SetUbrary, the library will be loaded into a library buffer in bank 0. If you 
use Setlibrary to select a library which is already in a buffer, DrawTools will switch to the aj^opriate buffer 
without reloading the library from main memory. ' ' ' ^ ■ 

DrawTools can allocate up to 5 library buffers. Only the libraries you use the most will be cached; in order to 
get the best performance from the caching mechanism, use the ResetBuffers tool when you are about to use a new 
set of libraries. This clears the old libraries from the library buffers in preparation to receive a new set of libraries, 
such as when a new level in a game is about to start. 

You can pre-load the library buffers when they are clear by using SetLibrary once for each library you will be 

using. *>, • ff»E ^ 

3.7 Mattes : Merging the Background with a Picture 

Using DrawAt, we can create animated objects that move about the screen by drawing, erasing, and redrawing. 
But these tools destroy anything they are drawn on. For instance, if the screen contains a picture of a tree, and we 
use Draw At to place a picture of a man on top of it, we get a tree with a 24x24 rectangle in it and a man within the 
rectangle. The picture is drawn "as is" overtop of the background. What we need is a way to combine the picture of 
the man with the tree. We want the empty pixels about the man to act as if they were transparent. 



f ■> 
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Matting is the process of merging a picture with what is on the screen by using a special matte, or mask, which 
indicates the portions of the picture which should be treated as transparent. If you have ased QuickDraw 11, you have 
already seen mattes used. When you create a cursor, you create a picture of the cursor and then you make a mask to 
indicate where the screen pixels show through. The pen mask works in a similar way: pixels marked as white show 
through. 



Fi gure 3: Mergin g. the Background with a Picture 
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DrawToois also uses mattes to merge pictures with a background. This is done with the **on" drawing tools 
(DrawOn, I>rawOnAt, ...). Each of these tools requires a matte to immediately follow the picture you are trying to 
draw. Creating a matte mask is easy. In PicEd there is a button named "mask". Whwi you click on the button, 
PicEd will create a matte for the current picture and place it in the following picture position. The effect is shown in 
the window with the red background. When the mask is made, each black pixel in the original picture is assumed to 
be transparent. To view the matte, edit i(. Each white pixel represents a pixel that will be taken from the 
background, and each black pixel represent a pixel that will be taken from the proceeding picture. It looks rather like 
a silhouette of the original picture. 

If we want to make an entire library of matted pictures, there is even an easio- way to create the matte masks. 

We draw pictures in each of the even numbered library positions (0, 2, 4 30). Then we can tell LoadLibrary that 

the masks are missing and that SetLibrary will have to generate all the masks in positions (1, 3, 5, 31) for us. 
The following procedure shows the pictures in this kind of library. Note that the pictures will be drawn on top of 
whatever was previously on the screen. 



Fx ample: Drawing the contents of a picture library with matted pictures 

Pascal: 

procedure DumpOutMaCtedLibrary { pathname t GSOSString) ; 

var TheLibrary j integer; { ID code for the library } 



begin 



'^^■ky&^i "mJ' , /if 
' ■ ■ ■ , -: 

TheLibrary i= Lo«dHbrmry( pathname, 0, $4000);! bit 14 = we'll need maeko! 1 
S«tLlbrary( TheLibrary ) ; { use this library to draw with } 
for y 1= to 3 do{ 4 rcwe } 



^ for X 1= to 7 do ( 8 picturee per row } 

rfiJ* *X^> odd(x) thenf Skip the masks a 1,3,... } 



DrawOnAt( x * 32, y 



U V ,.tSaJ»'>M':^3-i?.v7!,' ..^.■_i■ 

32, X + y * 8 ) ; { draw picture # x+8y ) ' ■ 



end; 



f>t annift*m} &5fcft>ow>ji| <'.H'-*^fi'^--fi^. ■.-(S. ?.> ^ii: rf ^.tV 



BASIC: 

PROC DumpOutMattedLibrary 
REM Load and eet the library 

T0OLB0X(-a«nAllM«Bk» ) j REM Generate matte maeks for even-numbered pictures 

FOR y% = TO 3 »tU -^H lliu L •TEU'+rsi^ji & ami*:/:.^. -i y,- v 

FOR X* = TO 7 STEP 2 f ^^'J^aJt^J i u-itrjoia t^; f^'fi/J^.t-; -Anf^ 'J :l" 
Screaix% = x% • 32 i"sm^S£iL ^ iiiJsic^ \-i^xf^Jt:i - 
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,1>;*J6f ,sh^ Screeny% = y% * 32 
S^itfi Pic^Jum% = x% + y% * 8 

fW i*»SiTf TOOLBOXi-DrawOnAt !Screenx%, Screeny*, PicNum* ) 

^^^^ ^* 4?"*^ -Mi i ii^ufyUi: AKHh Ayrrii iii^ir^ 

NEXT y% 

ENDPROC ^ 



,.,v. - 



If we don't want every black pixel to be treated as transparent, we will have to create the masks by ourselves. 
For instance, we may create a picture of a man with a black pixel for an eye. Create a matte mask using the mask 
button, and then edit the matte and remove the white pixel where the eye is. Now the eye won't be treated as 
transparent. r ' i ' 

Now we can create pictures like we see in video games which move overtop of the background. However, 
erasing these pictures becomes a problem. We can't simply use a blank picture as we did before because the 
background isn't blank. To erase the pictures drawn with draw on, we need to replace the piece of the background 
that lay under the picture. But when we use DrawOn, we've changed the background on the screen by adding our 
DrawOn pictures. 

The answer to this dilemma is to store the background in the shadow screen. DrawShadow and DrawMain 
tools let you switch whenever you want between the shadow screen and the main screen. ShadowOff turns off the 
shadow screen; you can still draw to it, but what you draw remains invisible until you 'Vipe" it to the main screen. 
ShadowOn turns the shadow screen on so that anything you draw will be copied to the main screen and become 
visible. i.--^ iiwj-^i i'.ttii^ (Ws"*-,- .. ...... ti^".^ v'i-.,f«-= , ' 



irtb , ..... . . .. 

.eS! -i) ^5^- 



Fi gure 4: The shadow screen animation 
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Rather than get into the details of how the shadow screen works, here's how we get around the erasing problem. 
Firet, we put the background into both the shadow screen and the main screen at the same time. The easiest way to 
do this is to use DrawShadow & ShadowOn and start drawing. Second, we use DrawMain and draw our matted 
pictures. The copy of the background that is sitting in the shadow screen remains unchanged. Finally, to erase our 
matted pictures, we use DrawShadow and draw empty matted pictures. Since all pixels are transparent in an empty 
matted picture, the background is copied to the main screen and erases any picture that we drew previously. If it 
soimds complicated, it is, but it's easier than trying to capture the pixels in the background each time we draw with 
matted pictures. ^ _ . , . . 

Example: This is the MoveABox procedure rewritten to move the box overtop of a background picture. It should 
help you put things together 

Pascal: ' ■ • * ^ 

procedure Mov^tettedBoxInADraWTooleLibrary { pathname ! CKOSString) ; ■ ' ' 

const Box = 0;{ box ie pictiare (picture 1 will be the matte mask) } 

Blank = 2; { blank picture is pictiire 2 {picture 3 will be the matte mask) } 
var i, delay i integer; BoxLib t integer; 
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begin 



MK3 



end; 



DrawBhadow; { remember to specify the shadow screen in CpStartup } ^ ^ 

CLS{0) ; { erase the shadow screen (and the main screen) ] 
{ Draw some stuff on the screen here - this will be in the background } "'' '"'^ 
BoxLib ;= LoadLlbrary( pathname, 0, $4 000) ,- { load the pictures } ^ 
S«tLibrary( BoxLib );( draw with this library } ^'■■• 
^OT ± x= 1 to 28 do beginf 28 times } Si^- ^mr^^<^ y-iSi i^-^ r^^'^.^^i -itiS ^- 

DrawMaln.M switch to the main scre^i } .f^5»' r-J il ifw ^>tlUv ':^.-iT:':r >''■■.=■.,■■ ■ - 

DrawOnAt( i * 10, 20, Box) ; { draw a box } 

for delay := 1 to 5 do WaitVB; (time delay = 1/6 second } y asaw-pj t :■ ..'y-utd 
DrawShadow;{ switch to the shadow scm } -ijwi^iY r-^ ■ ->*:. 1^ ^ i^/ 

DrawOn&t( i * 10, 20. Blank) ; i erase the box } -^1(1 (U*' ip. V ■ .ti,*^X--: .^.vj^ 
end; 



3.8 Pixie Power: Automatic Animation 



into mi {''i^it m nmoi-yt^. 'f-.tt 



Up until now we've been looking at how to draw pictures in PicEd that we can animate and move around the 
screen. You could do alt the animation yourself using the drawing tools to play back pictures in a specific order and 
erase them as appropriate. Animation involves not only pictures, but arranging them into sequences and moving the 
pictures about the screen. DrawTools has a special data structure to help you do just that, and it's called a pixie. It's 
sort of the software counterpart of a hardware sprite such have you may have seen on a Commodore 64. 

A pixie is an animated object that can move around the screen. Pixies are very flexible. They can be matted or 
unmatted. They can have a direction or stand still. They can temporarily become invisible and then reappear 
somewhere else. They can use pictures from more than one library. In the DrawTools' game demo, the mothCT ship 
and the bombs it was dropping were all pixies. K(-,»*----«%KSMLt?^;- ^-^ r^-- 

Each pixie consists of two parts: 1) a sequence of picture numbers and pixie commands; 2) a data record 
d^ribing the position and direction of motirai. We have afready seen examples of a picture sequence: we had to 
type in a picture sequ^ce to do the animation examples that we did at the start of the animation section. The size of 
data record depends on what type of pixie you create: a simple, coarse, or fine pixie. The simple pixie is used to step 
through the picture sequence; it doesn't actually draw or move anything. The coarse pi^ie is a 24x24 bit-mapped 
picture that has a location and a direction. The fine pixie is similar to the coarse pixie, exc^l that it can move with 
greater precision. For the rest of this section, we'll be talking about fine pixies because they are the most versatile. 
Most of what we'll discuss will more or less apply to the other two types. 

TTie data structure for a fine pixie data record is already defined for you in iE^scal if you are using the DrawTools 
interface file supplied with your E>rawTools disk. 



I ft 



Table 5: Fine Pixie Data Record (Pascal) 

Type FinePixie = record 

XVectorLow, XPositionLow : integer; 
XVectorHi, XPositionHi : integer; 
YVectorLow, YPositionLow : integer; 
YVectorHi, YPositionHi : integer, 
index : byte; 
status : byte; 

end; 
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Here is a description of each part of the record: 

X Posit ion - this is current position of the fine pixie (0..320, the same as the drawing tools use). If ''hi" is the x- 

coordinate, and the "low" is in tractions of a coordinate. Normally, you will want to leave the low's al zero. 

YPosition - this is the current line number of the pixie (0... 199) . i ^ ,^ 

XVector - this is the speed of the x direction (<0 is left, >0 is right)! ^ * " 1' ^ 

Y Vector - this is the speed m the y direction (<0 is up, >0 is down). ^ . ^^^.^ 

hidex - this is the location of the next picture in the pixie sequence; set to for the first. ^ . 

Status - user-defined value; we'll get to later. ^ ^_ ... 



IB 



BASIC : To create a fine pixie record, use the DIM statement or GET_MEM. For example, DIM 
MyPixie%(9): You will have to POKE the values into the record: the offsets for the different fields are listed 
in the reference. You will also need to use DIM or GET__MEM to create the sequences. 

For instance. XPositionHi = 100. XPositionLow = 0. YPositionHi = 50, YPositionLow = 0, means the 
pixie is at (100, 50). If XVector and YVector are all zero, the pixie is standing still. 



A picture sequence is simply list of bytes with the picture numbers to draw. TTie index to the sequraice is in the 
data record. 

Example: The following is an example of how to create a pixie of the swap disks animation that we saw in the first 
secrion. It uses SetPixie to create a new pixie. The constants dVisible and dFinePixie are in the E>rawTools 
interface file and are used here just to make things easier to read. SetPixieSeq lets you select the sequence of pictures 
that will make up the pixie. There are also GetPixie and GetPixieSeq tools that return to you a pointer to the data 
record or sequence for oa& of the pixies. 

Pascal: -■-''■'^■■^ '•^..^r,^--r, 

procedure Sett%3DiBkSwapPixie{Dialog_PicB_Path i GSOSString) ; t ■. 

■ type APictureSequence = array [0.. 9] of byte; •>^*» -ts^ifS^^ ■ 

var Pica t APictureSeqence; 'W^fc bum tvr>.-. -L'?^ ■ ■' ■} 

DisfcPixie : FinePixie; > 'i ^s^pr-)- sMif:. "' u v-: r. 

q~ DialogLib i integer; - -mv ki s^jVi liO ;^^^^Bl> r?? ■"sr-r-" : 

itJNf »V PicB[0] 1= 16; { list of pictures } ' ^V>Oi » if«.? •s.jM V^."? 

PicBlll 1= 17;Pics[2] .= ie;PicB[3] := 19 ; { in the animation } isOH-/.>?- ■'■■(.-- 

PicB[4] 1= 20;Pic6[5] j= 21;Pics[6] t= 22; ■-, ■-'.'"'"V;". _ 

-i^-r.^ Pics[7] t= 23;Pics[a] := 255;PiC8[9] (= 0; 

DialogLib i= LoadLibrary {Dialog_Pice_Path, 0, 0) ; f load the dialog pics f^^"' ' 
S«tPixi«{0, dVieible+dFinePixie, aDiekPixie) ; { pixie visible & a fine pixie J 
8*tPlxl«S«q{0, DialogLib, aPics) ; { pixie uses dialog. pics } 
{ & the picture sequence } 
with DiBkPixie do begin 

XPositionLow := 0;XVectorLow := 0; { place it at (50,50) } 

XPositionHi := 50;XVectorHi := 0; { and don't move around! } 

YPositionLow i- 0;YVectorLow := 0; 

YPositionHi != 50;YVectorHi := 0; j 
Index 1= 0;{ the first picture is } f'^OtO^W, 1 
{ the firBt in the array} ji^tKi^^J^VT J 

Once a pixie is created, it is easy to animate it with the AnimatePixie tool. Animate pixie moves the pixie (if 
necessary) and then uses the drawing tools to draw the pixie. Note: it doesn't erase the pixie for you, but we don't 
have to erase anything for this pixie because it isn't matted nor is it moving around. 
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Example : How to aaimate a single non-matted fine pixie. .^.^ -s*^! -ytii 'a jLstf v-f>^v sii? -.riU:' 

procedure AniinateDiekSwapPixiG (Diaiog_PicB_Path t GSOSString) ; 

{ — you can fill this in frcan the above example ] -- .■ 

DialogLib t= LoadLitarmry {Dialog_PicB_Path, 0, 0) ; f load the dialog pics ! ' 
a«tPi3ei«{0, dVisible+dFinePixie, «DiskPixie) ; { use pixie #0 ) ^ - w^. 
S»tPljcl«fl«q(0, DialogLib, aPice) ; { pixie usee dialog. pica } ' '"' "' 

" { --- Initialiee the data record in here } -^^^iHyi^^i--'^HV\--T--'- -r 

B.tLlbr.ry{ DialogUb ); n,. H^^r^^i^ .^,0/^^ 

for i != 1 to 100 do begin 

for delay i= 1 to 5 do Wal tVB ; {time delay = 1/6 second 1 
^ *" Anlmat«Pixl*( ); {animate pixie #0} ^:«ar-> sei vt^'ili .-'f f :r-' i -r-^ * 

end; ,i WSJOI!?} S-IVISW .|U«^ifSlJi ^ ;,- 

end; -S .0,?^'1P-.^, " tsiiJ'lW v . 

3.9 Pixie Commands - ^^^^mit^M -nxttii^ix ■ ■ ■ 

A pixie sequence can contain pixie commands. A command is a special instruction for the pixie, such as to 
change the pixie's vector or to switch to a different library. We have alre^y seen one pixie command: 255 is "end of 
sequence" command and every sequence must aid with it. The number following the md of sequence command is 
the position in the sequence to loop back for the next picture. In our disk swapping animation, we are looping back 
to position 0, the start of the sequence in order that the sequence will keep repeating over and over again. 

There are eight command that you can use with pixies, and they are outlined as follows: - ■ * ■ 

. ■ , ...... '■ . ■ V-'H 

255 - End of Sequence (All Pixies) 

Marks the end of a sequence; it's followed by the index for tfie sequence to loop to. It can also be used to to jump 

forward ma sequence. 5-^, {-m^fratt *i Efiff^^-;©*! :,i.fl5^a^0 [os.}p^it:?s ■■. A-.-.k-' 

254 - Change Library (Coarse or Fine) 

Switches to a different library; it's followed by a logical library number (The second parameter in LoadUbrary). 
253 - Change X Vector (Fine) 

Changes XVectorLow & XVectorHi; it's followed by the new low and high values, eg. 254, 0, 0, 2, changes low 



to and high to 2. 



/ \ r- i 



252 - Change Y Vector (Fine) 
This works the same way as Change X Vector. 

25 1 - Change X & Y Vectors (Pipe) 

Changes X Vector then Change Y Vector, a total of 8 new bytes plus the command byte. 

250 - Change Vector (Coarse) * 
Changes the vector word for a coarse faxie. 

249 - Change X & YVectors Relative (Fine) 

This command worics like 25 1 except that it ADDS the new vector values to the old ones. 

For example, you have a sequence of an aeroplane and you want to make the aeroplane bounce during the 
sequence. There is no way to know flie X & Y vector values, so you use 249, 0, 0, 0. 0, 0, 0, 1, 0, <picture> , 
249, 0, 0, 0, 0, 0, 0, 254, 255, <picture>, 249, 0, 0, 0, 0, 0, 0, 1, 0. If the aeroplane Y vector is $0100 (dropping 
one line at a time) when this sequence is used, the following will happen. The first 249 causes the aeroplane Y 
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vector to increase by 1 so the plane drops 2 lines at a time. The second 249 changes the vector by -2 to 0. The third 
changes the vector back to one (the starting value). The ptane does a iittle vertical bounce whether its gaining 
altitude, losing altitude, or flying straight. 

248 - Change Status (Coarse or Fine) 

The status field in the data record is for your own use. It works much like the RefCon values in things like 
windows. 248 is followed by the byte that you want stored in status. For instance, if you have a sequence of 
someone jumping, you can start the sequence with a 248, 1 and at the peak of the jump you can use a 248, 2. Now, 
to tell whether the player is jumping up or is starting to fall, all you have to do is check status to see if there is a I 
or 2. aJttmei cA c-ox .> ; -o_ 

Example : The following example is how to enbed speed changes right inside of a sequence. It's a sequence of 
someone Jumping, where pictures 1, 2 and 3 are to be repeat during the jump. Without the speed changes, the 
sequence would be 1,2,3,255,0. But we want a nice looking jump where the jump starts fast (reduce the Y 
coordinate by 2 each animation), slows when the peak of the jump is reached (reduce by 1), and speeds up past the 
peak (see Figure 6). Because all these speed changes are embedded in the sequence, all our program has to do is 
check the pixie position to see when the jump is over. 



Pascal: ^ 'ivs^noo s-i-. aM-anejiw ft . 

SeqfO] t= 253;Seq[l] i= 0fSeq[2] t= 0;Seq[3] t~ 254;Seqt4] i= 255f^ " ' ' -v -i" ♦'r.rii ■ A: ., - 

Seq[5] != l;Seq[6] )= 2;Seq[7) := 3; -^^fiPtKliO^ '^■A--.';- 

Seq[8] l;Seq[9] := 2;Seq[10] := 3; i<(rD'Ki'=^ 

Seq[ll] := 253;SeqU2] := 0;Seq[13] := 0;Seq[14] i= 255;Seq[i5] i= 255; ^, .. fij ,0 (:/-,rtir ■ 

Seq[16] 1= 1; '.^^","^'"S•'-^'' ''^^ift SKI ^r'^ ,■ ' 

Seq[17] := 253;Seq[18] j= 0;Seqtl9] := 0;Seq[20] t= 0;Seq[21] t= 0; 

Seq[22] i= 2; 

Seq[23] := 253;Seq[24] i= 0;Seq[25] := 0;SeqE26] := l;Seq[27] := 0; 

Seq[28] := 3; 

Seq[29] := 253;Seq[30] j= 0;Seq[3il j= 0;Seq[32] := 2;Seq[33] := 0; 

Seq[34] != l;Seq[35] := 2;Seq[36] i=3; 

Seq[37j j= 255;Seq[38] i= 34; 



Fifiure 6: A TvDicai JumoinE Seauence 


■1 

-2 i 




n 


V 







BASIC: -iizir-.vUiWxirv - <■ ■ 

REM Assuming Seq_Addr is the address of the sequence ■^^'^ •^•"ytx^ 

POKE Seq_Addr+0, 253 I ^.,rf. 

POKE Seq_flddr+1, OtPOKE Seq_flddr+2, OiPOKE Sec3_Addr+3, 254iPOKE Seq_Addr+4, 255 n ,; /■ 

POKE SeqJVidr+S, ItPOKE Seq_Addr+6, 2tP0KE SecLAddr+7, 3 ^ f^^. ., .^..^ 
POKE Seq_flddr+8, ItPOKE Seq_Addr+9, 2iPOKE Seq_Addr+10, 3 
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POKE 


Qf^rr Afid"r+ 1 1 




Qcirr aH(^>-+ 1 9 


POKE 










OcCj MTlClA ^ X O / 


POKE 


Seq_Addr+22 , 


POKE 


Seq_Adilf+23, 


POKE 


SGq_Addr+24, 


POKE 


Seq_Addr*28, 


POKE 


Seq;_Addr+29, 


POKE 


Se<5_Addr+30, 


POKE 


Seq__Addr+34, 


POKE 


Seq_Addr+37, 






Merlin 16+: 



OsPOKE Seq_Addr+13, OtPOKE Seq_Addr+14, 255:POKE Seq_Addr+15, 255 
1 

253 

OiPOKE Seq_Addr+19, OiPOKE Seq_ftddr+20, OiPOKE Seq_Addr+-21, 



tfV" 



,1 



POKE Se<5_Addr+30, Q:POKE Seq_Addr+31, 0:POKE Seq_Addr+32, 2 : POKE Secj_Addr+33 , 

2: POKE Seq_Addr+36, 3 
255. POKE Seq_Addr+38, 34 '"""^ ^ '"'^"i -. ^ ' 

253 ; Btart jvmp with a new Y vecTtor ^i'^S'**'^ .l>i^?W*:^ tr^f^^> ^ 



db 


■ 


adrl 




db 


go?: 


C&i 




adrl 




db 




db 




adrl 




db 






adrl 




db 




db 




adrl 

db 


VIS 


db 





$FFFEOO00 

1, 2, 3, 1 ,2 ,3 

253 

$FFFFOOOO „ 

1 ■-■ ■ . 

253 

$00000000 
2 

253 ; starting to fall! 

$01000000 

3 

253 

$02000000 
1, 2, 3 
255, 34 



{-2) move up 2 lines for each pictiire displayed 
display six pictures, moving up 2 lines each time 
nearing top of jump; start slowing down 
{-1) move up one line next time ^ ■ 

display picture, moving up one line 

; we're at the top of the jump; hover for one picture 

; don't move for next picture 

; picture 



; { + 1) move down one line each picture 
; picture ^ 

fall at full speed for as long as the seq. continues 
(+2) down two lines each picture 
pictures 

; end of sequence - keep repeat the last 1,2,3 



Example : Jumping with the above pixie sequence. 

Pascal: 

DoneJumping ;= false; 
repeat 

AnlmatvPlxl* ( PixieNum ); 

if HasIiandedDnScmething { PixleRec.XVectorHi, PixieRec. YVectorHi 

PixieRec. YVectcarHi : = 0; 

DoneJumping := true; 
end; 

until DoneiJun?)ing; 



then begin 



BASIC: 

DoneJumping t = FALSE 
REPEKT 

TOOLBOX{-Anim«t«Pixl« i PixirfJum% ) 

XVectorHi% = PEEK{Pixie_flddr+6) + PEEK(Pixie_ftddr+7} * 256 
YVectarHi% = PEEK(Pixie_Addr+14) + PEEK(Pixie_Addr+15) * 256 
IF HasLandedOnScmething [ XVectorHi%, YVectorHi* ] THEN BEGIN 

POKE Pixie_Addr+14, : REM Y vector to 

POKE Pixie_flddr+15, 

DoneJumping! = TRUE . ■■ . 

ENDIF " * - 



I 
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taSTTIL DoneJumpingl = TRUE , ^.^ sj-..-.^ 

3.10 Managing Multiple Pixies 1.7s. " . 

We know know enough to create an animated figure that can move about the screen, even overtop of a 
background. The final topic here is animating multiple pixies at once, especially about how to be careftil when 
erasing pixies. 

Throughout our pixie examples we've be«i using pixie to do our animation. DrawToois supports up to 16 
pixies at once (0 ...15). You can select any one of these pixies for your animation. However, there may be 
occaisions when you don't care which number you use. You could make a game where new bad guys can appear at 
random. At any point in the game, you may not be sure of how many bad guys you have already on the screen, nor 
do you know which pixies are being used. To make things like this a little easier, DrawToois provides two tools 
called NewPixie and ClearPixie. NewPixie returns the number of the first pixie that is not being used, starting 
from 15 and working down towards 0. ClearPixie lets you free up a pixie that you aren't going to use anymore. 

If you temporarily want to suspend a pixie without using ClearPixie to free up it's data record and sequence 
information, there is DisablePixie tool. When a pixie is disabled, it will not be drawn or moved, but it still 
exists and can be "started up" again by using EnablePixie. A pixie may also be rendered invisble by using 
HidePixie. A hidden pixie will move around the screen, but it won't be drawn. It appears again with a 
ShowPixie call. In the demo game included on the DrawToois disk, a bomb is disabled when it hits the bottom of 
the screen and it remains disabled imtil the Mother Ship is ready to drop it again. The Mother Ship is made 
invisible at one point in the game by using HidePixie. 

Using several pixies is easy with the Animate command. It works the same way as AnimatePixie, but it 
animates all the enabled pixies at once, and automatically calls SetLibrary when necessary. Animate works from 
pixie 15 down to pixie 0. If you have two matted pixies overlapping, the pixie with the lower number will be 
drawn on top of the other one. Keep this in mind if the OTder of drawing is important. If you want a pixie airplane 
to fly behind a pixie cloud, the cloud must have a lower pixie number. 

Hie most difficult aspect of working with multiple pixies is ^sing. Like AnimatePixie, Animate doesn't do 
any erasing. This is for two very good reasons. First, Animate can't tell which picture is blank, or in what library 
it is in, to use for erasing. Secondly, when you are animating more than one pixie at a time and they overlap each 
other, the order of erasing is very in^x)rtant. All the pixies must be erased before they are animated since 
overlapping pixies will interfere with each otha-. Some pixies may not even need erasing, Fuch as non-matted pixies 
with wide a wide border of pixels that squashes old pixels as it moves slowly arcoss the screen (as in AniDemo). 

However, there are two tools to make musing matted pixies easy. ErasePixie erases a matted pixie by 
copying the background on top of the pixie: this worics with both coarse and fine matted pixies (that are not disabled, 
of course). 

Example: EraseAllPixies will erase all that matted pixies. The main loop of a sinqple arcaob game would look 
something like this: 

Pascal: • .v. .^-->w 

Done := false; . , ' Ji'^ 



repeat 



Braa«AllPixl«a; . . 



{ move the pixies } • ' , frruM^ijU^<i . , ....-^e* i>/-^_..-.-: 

Anlmata; , iK*t?^ - .^>^^Lb^ys_>>,s.H . XS££ t - # l^?'-.-:"- ,. 

until Done; , -■ •» ; *ifc?^ . _ . ♦ (♦i*-(f)fcA7*i^j^J ,*f i 

BASIC: V - 

Donel = FALSE % 3D^? •■ t\ -y-fitiT-ts-. /,^ 

REPEAT ■ 
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REM move the pixies 
TOOLBOX(~Anim»t« ) 

UNTIL Done! = TRUE 



^ 
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4. Other Functions ^>»^^>^-^^- .M:.^ 
4.1 Random Number Functions ^ . 3t.r«Hife^ v. t^.^ ^. : -.^^n. . 



"J 



DrawTools has three convenient random number tools. These all use QuickDraw IPs Random, which returns a 
random integer. R\D returns a random integer between 1 and the another number, like BASIC'S RND function. 
Odds is a boolean function that is true the given percentage of the time. NormalRND is a special funtion that 
returns a normally distributed (bell curved) number between 1 and another number, c twa i'^i i ^ : 



IB 



You can use SetRandSeed to set the "seed" for DrawTools' functions as well as Random. (The seed 
determines which random numbers will appear, if you set the seed to a certain the number, the random 
numbers returned by Random appear in the same wder.). 

Example : Suppose your are writing an adventure game. The player could find a treasure chest, and the chest may be 
booby-trapped to explode 30% of the time. If the chest doesn't explode, the player gets 10 to 15 pieces of gold. 
You could program it like this: 

Pascal : 

ExplodeChest 
else 

UOV bsi GoldPieces i= 9 +RND{6}; *i'V tltl iihf 4ooTifttKliV> miiV)'? t^-v -v. '^^^ 

BASIC ■ "'^ '"^'^ '^"-^ ^ ^-p^ iTKhfsTi* .&n«s ^* - 'S ^ > ' 

TOOLBOX(-Oddo : 0, 30; Reeult% ) (.^CriEywXffT >tf*k» C Si^.^^ 

IF Reeult% <> THEN GOSUB ExplodeCheat -' ' '{^tf*-J'n^^V^^lmfi''ini-. 

IF Result% = THEN BEGIN 

TOOLBOX(-MID .-0, 6; RsBult%) t REM or use BflSIC'B RND - t^iii^^-fri-^ 4 ■> " 

GoldPieces% = 9 + ResulC% -^j^ir^j^ - ■! jfU f-^,'^ 

ENDIF ..-fy^ & 1 j , 

Example : A player in your game could also pick up a shovel lying abandoned in a corridor, and you want the shovel 
to break after an average of 20 uses. If ShovelUses is a variable with the number of good uses left in the player's 
shovel, you could write this: - m.tLtii^i^i^.x - 

Pascal: ShavelUsea := NormalRHD { 40 ); ?i f?f?f ewofls^ ■ 

BASIC:tooLBOX{9 8, 101= 0, 40; ShovelUBee%) a... -.-^-ttCiiftmsV^I*^ -^101*5^^ 

With NormalRND, ShovelUses will usually have a value near 20 (half way between 1 and 40). However, there is a 
small chance the the shovel could have as many as 40 uses (a super-shovel) or as few as 1 use (a real "lemon"). 

4.2 Reading the Joystick ,{ >.Hw^itc> ,i »s 

There are 3 tools for reading a joystick on yourllGS. To test the joystick buttons there are two tools: GetFire 
andStillFiring. StillFiring is the easiest to use; it is if the joystick buttons are down, and greater than if they 
are up. GetFire is only greater than when a button is first down. If a button is held down, GetFire will be until 
the button is released and pressed again. The actual number returned by these tools is a sum: button has a value 
of 1, button 1 has a value of 2, and both buttons have a value 1+2 = 3. 

Getjoy will determine the position of the joystick, either horimntally or vertically. GetJoy(0,0) returns the 
horizontal position: a value <0 if the joystick is held to the left, if it's in the center, or >0 if its held to the right. 
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GetJoy(0,l) is <0 for up, for centered, and >0 for down. ^ 

ExajD^: Using GeUoy and StillFiring in a game. mi^t:mij'i ''Hi -''^ m-?*-' ^ ' ^ 

Pascal: - ~ ■ ■ ^ 

if OnALadder then 

VerticalDir := Q«t Joy (0, 1} ; 

.arnf^^ ^-j^gg ' rssi^fen s Amsi.*. ii/Ji /'j^v-*f*i - ■ 

mi\ oi>; HorDir t= GstJoy (0, 0) ; "^^ ^'^•n*^^ iRvit, -i mtVrriti a- Hiity' ■ - >■» ■ 

if Stillrirlnff (0) > then FireGun; ^^-^'^ ^^^'AiiJ ^^cKf^^-.•^^!^.. a?,?t \''^s:.ifh:f, -• ^ • • 

BASIC: '^"^ ^^"■"^'m^' -mT "<A^i^ srtj los If^^h^^iitc '--i. --k:- • 

t*iOt»g« IF OnALadder! THEN BEGIN frifimim fiT^.n.'^i rfr-i^*'?.- a-- .im'y.: ■■ 

TOOLBOX (-a«t Joy ! 0, 0, 1; VertDir%) la^SrtJfti tit^S^V^ T- ^■'■'^ii'e.'O ' ' '" 

ELSE BEGIN 

tfti^m T00LB0X{-O«tJoy : 0, 0, 0; HorDir%) .-jSTjaa «iiaticsW^U ts-:: i(fliihW l-'^ ttHl, Ob'^kim i -■ 

T0OLBOX(-6tillPiring : 0, 0; Buttcais%) Kv^<y^^ ' 

IF Buttons% > THEN GOSUB FireGun " """" ? 

■ til ' ■ ": 

4.3 Game and Network Drivers '^'^'^■^ly'-^l^ir^C 

The newest version of DrawTools will let these 3 tools worlc with devices other than a joystick provided you 
have a game driver. A game driver in DrawTools operates a substitute device for a joystick, like the keyboard or a 
trackball. Up to 4 game drivers can be used at one time. (For more information on how game drivers work, consult 
Appendix D of the refaence.) -i - : .=;,(,>; jo i 

Three sample game driver is included in the DT.Drivers folder on the DrawTools' disk: $ ''i 

Joystick. Drvr - sinq)Iy opoates the IIGS joystick using GetJoy, GetFire & StillFiring 

Keypad. Drvr - simulates a joystick on the lIGS keyboard (with the Event Manager's GetNextEvent) 

• keys 1...9 specify your direction 

• 0, -, +, * are fire buttons 0, 1, 2, and 3 respectively 

allows you to change your speed (-2,0,+2) or (-1,0,+1) ' 
?. t^^i Keypad. Drvr - simulates a joystick on the lIGS keyboard (with the Event Manager's GetNextEvent) 
" keys y,u4,hj,k,b4i4n specify your direction ■ ■ ' ■''^ . - •. . ■ 

• space,a,s,d are fire buttons 0, 1,2, and 3 respectively 

• fallows you to change your speed (-2,0,+2) or (-1,0,+ 1) ' '^^"^-^ ^ 
Not all languages suf^xjrt the system loader directly: to load a driver, you can use LoadDriver. To start the 

driver, use the DrawTools' SetGameDriver tool. 

Examle: Loading and starting a game driver (as device #1). - .Q>«^--*aj^>- (fi. -V 

Pascal: 

DriverPtr i= LoadI}rlv*r( DriverPath ); 

8«taaB.0rlT.r( 1, driverPtr ); ^Mi^Vtj J, ^ffl Umht-^-^- ■ 

BASIC: ^ voi fi ^"vi®"-! v.»i .ff'_ri>j * r " 

REM LcadDriver requires a Pascal string. . ■ •> ■ j'-t - ' -V - 

'i^r TOOLBOX(-Lo«dDriT«r i 0, 0, PathHS, PathL*; DriverPtrL%. DriverPtrH%) •.it';,-^> , -■ 

MflA^ -i TOOLBOX(-S»tO«m«Driv«rt 1, DriverPtrH%, DriverPtrL%) ..^ -'.A>^ .-. 'j'-ti'--- : 



2<t; Now whenever you use GetJoy, GetFire or StillFiring with a 1 (not 0) as the first parameter, DrawTools' will 
use the new device in place of a joystick. . ,, ., , „ ,., , , 
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There is also a second kind of driver you can install, a net driver, that keep you informed of devices operating on 
other ilGS's across a computer network or a modem. ^^.^^^.^ ...^ ,* . . 

Example : You are writing a Tetris^" clone to work with 2 players on a network. The object of the game is to be the 
player who survives the longest. What we need to do is; , 

(1) use SendNetwork to synchronize the start of the game on two different computers . . , 

(2) use SendNetwork to tind out who "died" first. 



Pascal: 

Const AbortGame = 8/ 

GameAborted = 1; 
ReadyPoGo = 16; 



Var 



NoQnd = 0; 
Qiid : integer; 
Data ! integear; 



{SendHetwork cede to aJDort a game} 
{S.N. code for Bomeone aborting a game} 
fdefine our own code to signal} 
{ that we're ready to begin playing} 
is. N code for no cctnmand} 
^ { SendNstwork ccmmand wDrd } 

[S.N. data word } 

- ■ 

^irt'^ t signal the other ITGS that}j^^c-<; .',y'.{.:. 
.^■fe feWt { we are ready } 

{ check the network } 
{ignore everything unleea other IIGS} 
{ ia ready, too} 

K.„until Qnd = ReadyToGo; . «i . , 

{ both IIGS'B will only get here by both sending "ReadyToGo" over the f . ' 
{ network. This process is scmetimee called "handshaking" ] " 



begin [main program} ^^^JaiV 

{ do any initialization 1- -Sfi SB - 
repeat J'ffif^ .VS. 

axii^ita Cmd f= ReadyToGo; 

S«ndH«twork( Cmd, Data ); 

if Qnd <> ReadyToGo then Cmd := NbQttdf 



ImDead i= false; . , 
re^>eat 

{ do the Tetris stuff in here } 
if ImDead then 

Qnd 1= AbortGame; 
else 

Qnd := NoQnd; 
B«ndN«tworlc( Oai. Data ); 
until ImDead or (Qnd = GameAborted) ; 
if ImDead then 



else 



end; 



WriteLnCYou lost to the other player. ' 



WriteLn ( 'You won! 1 ' ) ; 



i if player "died''/loat } 

{ inform other GS that we lost first } 

[ else juat check the network } 

[ done if dead or other player dead } 



4.4 Printing Tools 



For assembly language progranK, these are a simple set of tools for displaying Pascal strings and integers on 
the super hi-res screen. Several of the printing tools have a mode word that comes after the rest of the parameters: 
with this mode word, you can specify whether you want a carriage return, the rest of the line to be cleared, or if you 
want to tab over to a new column. 



Example : Printing in assembly language. 

Merlin 16+: 

Ready2 Print 



in any new grafport, use _Ready2 Print 
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-Print #Stringi;#0 
-Printint #$i234;#$8000 
Print #String2;#$8000 



Btr , "The number is ' 
etr 'All done. ' 



Stringl 
String2 

Output: 

The number ie 4660 

All done. ***^-^ '•*^- 



home the cursor to top of screen 
display Faecal string String! 
display value of $1234 & do a C/R 
display String2 and do a C/R 



i." 



4.5 Interrupt Tasks 

In Super-Hi-Res graphics mode, the con^uter can be interrupted when a certain line is about to be drawn by the 
monitor and perform some quick task. By using interrupts, you can, for instance, have several different border 
colours, or can cause different sets of palettes to be available (512 colours or more instead of 256). Each task has a 
task header, which, strangely enough, need not be at the head of the task at all. A task could have more than one 
header, one for each line which is to invoke the task. Needless to say, don't touch the header if the task has been 
added. Once you've defined (and, hopefully, debugged before hand) your tasks, ^able the interrupts 
(EnableSCBInts), add the tasks (SetSCBInt), and start the execution of the tasks (ResumeSCBInts). 



Example : How to put 512 coloitfs on the screen instead of only 256. 

To do this, we need two sets of 16 palettes: one for the top half of the screen, and one for the bottom half We can 
use the interrupt tools to switch the palettes around. Once ^ResumeSCBInts is used, the palettes will be swapped 
"in the background", and the main program can do other things. 



Merlin 16+: 



-BnmblvSCBInta #-1 
~a«tSCBInt #Line99Header 
i j«:sj1 .-Jaoi -fl«tflCBInt #Linel99Header 
JRvauBMSCBZnts 

Line99Header adrl 

■ dw 99 ■ Mioh { 

dw SIM4D 

adrl SwapPalettes 
Linel99H©ader adrl 
dw 199 
dw SD44D 

adrl SwapPalettes 

SwapPalettes 

phd 



liO i i 



swap, in and out, the 16 palettes here 
plb 
pld 



1 

;the line this header at^lies to 
; signature word 
^.j^invoke swap palettes on line 99 



; reserved 



(•invoke again at 199 
;our interrupt task 
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4.6 Scolling the Screen l • : 

The lIGS is too slow to scroll a screen quickly enough without ugly, slanting jaggies appearing as different 
portions of the screen are at different stages of scrolling. DrawTools has a couple of screen scrolling tools to shift 
the screen contents and fill the void created with a picture. To scroll faster, the screen is divided up into small 
blocks: if two adjacent blocks look the same, they are left alone; if they differ, they are scrolled. The result is diat it 
appears that the whole screen is scrolling, but only the portions that need to be moved are moved. 



Figure 7: A Scrolling Block 
Check Byte 



■5- ■ ■■L.'if'-j:;'!/'; 

ft. 'r^:■'■^ 



Each block is four bytes wide, and eight bytes high; on the screen, that's up to 40 blocks across, 25 blocks 
down. The upper-left byte in a block is called the check byte. If the check bytes of two adjacent blocks match, the 
blocks are assumed identical and no scrolling takes place. Obviously, not every picture can be scrolled using this 
method. Pictures must be carefully constructed, making sure the check bytes differ whoever a block differs from a 
neighbour. By this method, and clever art work, a picture can be made to look smooth and natural, and still scroll 
very quickly. 







You can make two check bytes look the same but be treated as differing by using a pixel whose colour is 
equal to another (eg. two greens (#1,#2) of the same shade; one check byte can use green #1, and the olher 
green ^ - they look the same, but they are actually differwit byte values). - ^esta-i^attK;}^^ '.- 

The scroll tools use a scroll record, containing a descripticm of the area of the screen to scroll, and of the picture 
to be scrolled in. Scrolling may extend between any two screen lines, provided that the range is composed of 
complete blocks (8 lines each). The scroll record parameter for width allows any rectangular picture to be scrolled 
onto the screen. A scre«i wide picture has a width of 160; DrawTools pictures have a width of 12. 



4.7 Other Tools 

DrawTools has a variety of other tools that may be useful in many programs. '^JVTSB *»st 

• the work cursor, a pair of rotating gears, an alternative to the watch cursor. 

• HLoad and HSave, to quickly and easily load files to handles and vice versa. 

• a bar graph drawer ^^^"^ ' 

• a tool that let's assembly language programs call certain tools at fester speeds 

• GetMHz returns the speed of the GS to the nearest MHz 

• a tool to print windows or the screen on your printer 



Exanq)le : How to use the work cursor. 

Pascal: 

PforfcCuroora (6) ; {animate the work cureor every l/lOth eeccnd} 
for i 1= 1 to 20000 do begin {StillWorJcing calls} 



DrawTools 3. 1 



i r= j - 1; 

S til Iffor king; 

>esT6S^E{ end; -W^. g»rtef**2 .^k'- 

Jt;ifc InitCureor; 

BASIC: 

TOOLBOX (-WorkCur»or 2 : 6) 

FOR i% = 1 10 20000 
j% = j% + 1 



dSte-'-ns ^Jfca^ ^**y<:.* a n?: vaj?;- <it;\ ■ : ■ 

-h fits) v'^A .-wBwi s:ds»i)<^ u";^-*^^^ - f -: ■ 



TOOLBOX {-St ill Working ) 

NEXT i% 



TOOLBOX (4, 202) 



Merlin 16+: 

~lforkCuraor3 #6 

LDA #20000 
STA i ( 
INC j 

StillWorking 
DEC i 
BNE locp 
InitCuroor 



loop 




Exairq)Ie : Drawing a packed super hi-res screen (filetype $C1/$0001). This format is used by 8/16 Paint™ Screen 
Pictures and DreamGraphix^" PackBytes 16/256. For other programs, save the picture as an unpacked screen and use 
Lib.Converter 1.2 to convert the picture. 



TML/Complete Pascal: 

P2GSString{ 'MyPic', pathetr }; 
■MVi'sfi picHandle := HLoad{pathBtr, $C1) ; 

S«tBackground2 ( PicHandle, ); 



»t» ^y:^ il;-^ (jte^^t fi-; Y 



ORCA/Pascal: 

PathStr.size ;= length{ 'MyPic' } ; 
PathStr . theString := 'MyPic'; 

PicHandle := HLoad(pathBtr, $C1) ; .KifiA 'io dibits % m\ vmtj 
S«tBaokground2 { PicHandle, ); 



BASIC: 

REM Basic doesn't support GS/OS strings directly 

RQfl Use GET_MEM to get 32768 bytes, and load the picture with BKJAD. _.. , 

TOOLBOX{ -S«tBaokground3 : PicH%, PicL%, ) 



Merlin 16+: 

PathStr strl 'MyPic' 



-HLoad #PathStr; #$C1 



S«tBaakground3 ; handle is still on the stack 



1Xm-\ir- Triif ==,iy -M V.,-.". ■ .v-. -. -t 



DrawTools 3.1 



II. Reference 
Introduction 



This is section explains the layout of the reference section, and defines some of the terms used. For a more 
general introduction to DrawTools, please read DrawTools Introduction manual. ikMU^-t JiiUJv"? ^IKV' 

j'^f'^ mt v*fi Jii'^'i'- ofi 1 "v '.: . ■ 

Layout of Tool Entries .*{y>ii . 

DrawTools provides over 100 tools. For convenience, these tools are divided up into different categories by use: 

Housekeeping Tools, Low-level DrawTools, Drawing Tools, Library Management Tools, Animation Tools, 
Screen Tools, Scrolling Tools, Palette and Colour Tools, SCB Inlanipt Tools, Printing Tools, Driva- Tools 
and Miscellaneous Tools. . •- :^ >'-^i ! ■ ' 



Each individual tool is described in the following format: 

DrawVersion ($0462) 

Returns the version number of DrawTools. 
Examples : int :- DrawVersion; 

TOOLBOX( 98, 4 : 0; 'mt% ) 
Parameters : int (word) - the version, ie. $0301 
&Tors : none 



Definitions of Terms . 



.' <y^A}r-"p iiir-ft i'y. v.'-^ii - .r^' • 
The tool name and number, -^if^i sm'-t^ ■ 
A description of its use. 

An example in Pascal & BASIC. -r j ^ 

(BASIC: Include 's for each result word!) 
A description of each parameter. , - 

A description ofeany errors it may return. 



.-icy^iT f'Sr^' f;><'-t 



Here's an explaination of some of the terms you may aicounter: 
Absolute Screen Position: A pixel number, 0...31999; ASP = ( x / 2 ) + y * 160. 

' ^ ^^ •:>tii 3 
Pixel 159 ( 159, 0) *aisw • :.v, . 



Pixel 
Pixel 160 




Pixel 3 1999 (319, 199) 



Booleans & BASIC: Treat the b(X)leans as an integer: means false, and anything else is true. 

Bound lines: Bound lines are used to specify a range of screen lines. In DrawTools, bound lines need not be in 

asc^ding order. j^^itl^As^ i.'i- 

Colour word: An RGB colour word of the form $ORGB, where R.G,B are the amounts of red, grera & bhie. 

Current Drawing Screen: Some tools will work with either the shadow screen or main screen, whichever is 

active. 3« >Xe«JOCM 

Library buffer: a 9K area in back where recently used libraries are kept. " iisie^) ifjj, ; jr^.- ^jf^a^ 

Main Screen: the slow drawing area in back $E I , used by most applications. 

Nil pointers & BASIC: use zeroes. 

Shadow Screen: the fast drawing area in bank $01. 
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Housekeeping Tools 

Hiese are the standard tools in every toolset. 



DrawBootlnit ($0162) 

Should never be called by an application; does nothing. 
Examples : should never be called. 

Parameters : none 
Errors : none 



DrawStartUp f$0262) 

Starts up DrawTools for use by an application. It must be made before any other DrawTools call. It does the 

following: - -;;i.fXi) afcR5^13.- y.ii;;.i* j^, ;: 

* Searches for the special QuickDraw locations ■ '*>'^- •= -' 

* Saves user ID with auxiliary type $F (used for all memory allocation, including HLoad's & Loadlibrary's) 

* Allocates one library buffer (about 9K in bank 0) , . 

Examples: DrawStarf Up( dpage, MMID ) ;«oo?»»Vw»n<T «?: Kif ;r-;kpiis-;" 

TOOLBOX(98,2:dpage%,MMID%) 8^ V/.i?£ 500T 

Parameters : dpage ( WOTd) - address of direct page workspace »s& - «?3!ss!»£»a^ 

MMID (wOTd) - memory manager ID of your application sant^a ■*^p:r» 
Errors : none 



DrawShutDown ($0362) 

Shuts down DrawTools when an application quits. This routine does the following: *o fso#Sei>ai<?r» r^.t ^^.v.. ■; 

* Ensures the system interrupt manager is in its normal state • 

* Deallocates all memory used (including HLoaded handles & picture libraries) 



* Shuts down the net driver, if one is installed 

* Restores shadowing to its original state j. 



Examples : 

Parameters : 
Errors : 



DrawShutDown; 
TOOLBOX( 98, 3 ) 
none 
none 



fm b)!?«i 



DrawVersion ($0462) ^ 

Returns the version numbCT of I>rawTooIs. 
Exanqiles : int := DrawVersion; 

TOOLBOX( 98, 4 : 0; int% ) 
Parameters : int (word) - containing $0301, meaning version 3.1 

Errors : none 



■ ' R? saw » rt^itW r^t-i- . 



DrawTools3.1 ! t. ^-itv. 

DrawRpset ($0562) 

Resets DrawTools; disables SCB interrupts. This tool must not be used by an application. 
Examples : should never be called 

Parameters : none ^ttSjafeg-.' m ti-joi nta, s^^^l j 
Errors : none . ■ r- ■ , , ■ , .»v<o^-— 

DrawStatuS ($0662) ■ " !«U .9j>:t«aijq ?Jt js^j/.'f •f7»»<tt( ; ••■ 

Indicates whether DrawTools is active. .(*sir<Rj| v^^u-'^ . v-. ,- 

Examples : boot := DrawStatus; ;;fK?'3i;gix?s*s5! V'j,;t:i. 

TOOLBOX( 98,6 : 0; bool% ) jto \X(>^XV>T 

Parameters ; bool (word) - TRUE if DrawTools has been started up. ^^y . , , ., 

Errors: none -ms^^ \se^^^ -^- ■■ f^ifj^ia 



K :■»* ij^ ftsidft Isffi' 



."punnfU ^-fea^ ifsspftir^ sjSt v,^ i^%tf»i r^*! 'a. WKja>ii >'S : -ti). • 
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Low-LevelTools 

These are tools for changing DrawTools' parameters and/or pafonnance. 



? V -• -11. t' 



ExtcndBuffers f$4A62) 

Allocates as many library buffers as possible. Use this to reduce the time it takes to switch between picture libraries 
in graphic intensive programs (like games). 

Examples : ExteaidBuflCTs; -vk/ i 

TOOLBOX( 98, 74 ) * i^J"*-^ ' '^.^^ -.^OH^'M'- 

Parameters: none trt ffkx-^Twfc^I ii :-?VmT - ;• I. ...v..--..-. 

Errors: $6209 - not enough bank memory for another buffer i*^^^'^ ^ ' 

$620A - already have maximum numbw allocated 



ResetBuffers ($7062) 

Clears the library buffers. The library buffers act as a caching mechanism for libraries: ResetBuffers clears the cache 
memory. Use this when you are going to using a new set of libraries. For example, when you begin a new level in 
a game, ResetBuffers will let you access new level libraries more efficiently. 
Exanq)les: ResetBuffers; 

TOOLBOX(98, 112) 
Parameters: a<me 
&Tors: none 

DrawPos ($0B62) 

Returns the absolute screen position for the next bit-mapped picture call. 
Examples : int := DrawPos; 

TOOLBOX( 98,11 : 0; int% ) 
Parameters : int (word) - 0...3 1999 

&Tors : none ' 

SetPrawFos ($0C621 

Sets the absolute screen position for the next bit-m^)ped picture operation. 

Examples : SetDrawPos( int ); 

TOOLBOX( 98, 12 : int% ) 
Parameters : int% (word) - 0...3 1999 

Errors : $62FF - the position is otf the screen 

PrawPage f$0D62) 

Returns the location of the buffer for the current picture lilnitry. 
Examples : int% = DrawPage; 

TOOLBOX( 98, 13 : 0; int% ) 
Parametei^ : iot (word) - the bank locati(Hi of the active set of pictures 

Errors : none 
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SetPrawPage f$0E62> 

Sets the location of the current picture buffw. j-^'l" gftfWfi^CI 
Exaoiples : SetDrawPage ( locn ); ' ' ^' 

TOOLBOX( 98, 14 : locn% ) 
Parameters ; locn (word) - the bank location of the active set of pictures 

Errors : none , • , . 



DrawMain ($01*621 

Directs I>rawTools to use the main screen (bank $E1). The current grafport is also forced to the main screen. 
Examples : DrawMain; 

TOOLBOX( 98, 15 ) 
Parameters : n«ie v, . 

Errors : none 



f lC„i.l^ vutkIsI tf»r>Tir: ^ *rt»tsr| - Orji;w; .>^.; 



Exan^iles : 

Parameters : 
Errors : 



DrawShadow ($1062) 

Directs DrawTools to use the shadow screen (bank $01). The current gralport is fenced to the shadow 
of the main screen. Micol Advanced BASIC'S shell interferes with this command, but it will work 
applications. 

DrawShadow; 
TOOLBOX(98, 16) 
none 

ncme , ^ 

.V, - .- .. 



screen instead 
in stand-alone 



if5tn*^y ?s?T)!fi6 ?^ m i^-^a^ ;■ ^ 
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Drawing Tools , , . , ^ 

These tools draw bit-mapped pictures trom picture libraries, or produce masks 
for matted bit-mapped pictures, without any animation. If you are using pixies, 

see the animation tools. 



Draw f$09621 

Draws a 24x24 bit-mapped picture at the current screen position and advance to the right. . ^ ^ . _ 

Examples: P^P|f.>; ^ . ^ l^^t^V ^m^) ^ um ^^t-^^^ ^ 

TOOLBOX( 98, 9 : pic% ) ^i^u 

Parameters : pic (word) - picture in the current library (0...3 1) ^ j **00 ' 

Errors : ncme ' ^ ' ^ _ 



Draw48 f$0A62> 

Draws a 48x48 bit-mapped picture at the current screen position and advances to the right. ^ ^ 

Examples: Draw48(pic); ...^ ^ ■ --^^ ^(-^-T.. 

TOOLBOX( 98, 10 : pic% ) ^^^.^ 
Parameters : pic (word) - picture in the current library (0..28) 

Errors ; ncme .^^At, .... rr 



{pi ,«t)V^:-0.KM7^ 

P^ a^YAt f$H62) 

Draws a 24x24 bit-mapped picture at the specified screen position and advances to the right 
Examples : DrawAt( xco, yco, pic ); 

TOOLBOX( 98, 20 : xco%, yco%, pic% ) 
Parameters : xco (word) - x-coordinate (0..319) 

yco (word) - y-coordinale (0...199) 

pic (word) - picture in the current Ubrary (0..31) 
Errors : none (if bad coordinates are used, the picture is drawn at the upper-left domer) 



Draw48At ($15621 

Draws a 48x48 bit-mapped picture at the ^>ecifled screen position and advances to the right 
Examples : Draw48Al( xco, yco, pic ); 

TOOLBOX( 98, 21 : xco%, yco%, pic% ) 
Parameters : xco (word) - x-coordinate (0..3 19) 

yco (word) - y-coordinate (0...199) 

pic (word) - picture in the current Ubrary (0..28) 
Errors : none (if bad coordinates are used, the picture is drawn at the uppCT-left comer) 



DrawOn (S2262> 

Draws a matted 24x24 bit-mapped picture at the current screen position and advances one position to the right. 
Examples : DrawOn( pic ); 

TOOLBOX( 98, 34 : pic% ) 
Parameters : pic (word) - picture in the current library (0..30) 

Errors : none 
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Draw480n ($23621 -r*.-.-^ ,,7,, ... , ,,,, , ,^ 

Draws a matted 48x48 bit-mapped picture at the current screen position and advances to the right. . -:>;r>(i.t;.> 

Examples; Draw480n( pic ); , . 

TOOLBOX(98, 35:pic%) M) ^^-^nHimifyci-i -riiW, * .-M 

Parameters: pic (word) - picture in the current library (0..24) r?!!iri^*r,5jt3 y-VJtr^^<^. - : 

Errors: noae .' J; i?K-i^:v>.?- -f.": 

PrawOnAt ($2462) ;:<;;>'.Xt 
Draws a matted 24t24 bit-mapped picture at the specified screai positi(m and advances to the right. t ■ . . .V 
Examples : DrawOnAt( xco, yco, pic ); hcMH^i ^ '-r^'tp 9 > +'o. »i^^ 

TOOLB0X( 98, 36 : xco%, yco%, pic% ) .ssO-Mji-^ ..>;■; .-,. ■ 

Parameters : xco (word) - x-coordinate (0..3 19) ilH ,m )>-r.>S.K>'?1 

yco (word) - y-coordinate (0... 199) 'leoc . ■;- .^-;!-- c 

pic (word) - picture in the current library (0..30) . - 

&Tors : none (if bad coordinates are used, the picbire is drawn at the upper-left cornea*) ^ -V: ^ ^ > .■ -c- •= 



Draw480nAt ($2562) ^ ■-■^■K;iv. 

Draws a matted 48x48 bit-mapped picture at fee specified screen position and advances to the right. .-j v 

Exanq}les : Draw480nAt( xco, yco, pic ); , w.^: r;-^ -t' 

TOOLBOX( 48, 37 ; xco%, yco%, pic% y>i^ ^5j5(*H-d5'.g 'i^w-HiM r>' .-r jTi-- . 

Parameters : xco (word) - x-coordinate (0..3 19) T >jssj(ns*>ft^ yS^Ofs^i^t^:". 

yco (word) - y-coordinate (0...199) ( * ? )ariC5g, iOQl' 

pic (word) - picture in the current library (0-24) , > • - -^^^Vi--.^ 

Errors : none (if bad coordinates are used, the picUire is drawn at the upper-left comer) 

GenMask ($2162) . m Omi - 1 

Generates a matting mask for the specified picture and stores it in the next picture position. - :-^r 

Exaiiq>l^ : GenMask:( pic ); ^ 

TOOLBOX( 48, 33 : pic% ) 
Parameters : pic (word) - picture in the current library to make a mask for (0..30) 

Errors : naae 



GetAllMasks ($2662) ' 

Generates a matting mask for every even-numbered picture in the current picture buffer, storing each mask in the 
following odd-numbCTcd picture position. 
Examples : GenAiiMasks; 

TOOLBOX( 48, 38 ) ^ ^ 

Parameters : none 
Brors : ntsie 
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SetBackgroundt ($3962) 

Draws a packet! super hi-res screen (filetype PNT/$00O0) on the current drawing screen. The handle is left unlocked. 
Examples : SetBackground( Background); "wsot-.U i& &s^h> bis^-:i-mhi^7^'i- t\r**/-: 

TOOLBOX( 98, 57 : BackgroundH%, BackgroundL%) ! ^tq ::^m'^%^Q '-i- - , ■■ 

Parameters : Backp-oundHandle (long) - handle to packed picture i/' C«3.iiX.J f 

Errors: memory manager errors ^,,Q) "ftii:^*! tftrres-i ^ f^A ^'>-^^ri • Or^y*ir } .^i-:^ • •....-^ ■■■ 

t See SetBackround2. ssf^.: 



WipeOnt ($5562) 

Wipes a 24x24 block of pixels from the shadow screen to the main screen at the current drawing positionu 
Shadowing must be enabled. rf 3S( ?iAi#>wjirKi -^.1; 

Examples : WipeOn; ( ^<<^X ' -^^ j'<Oe-itX> ' 



TOOLBOX( 98, 85) m I v ^ - ) o 

Parameters ; none ..0) a0Ki^i&i»x ■ 7 

Errors : none 'fS ^ktij::) wt* ?5 i?sH;sT^ ■ • 'r^- > ->*(j 

t For use with pixies, see ErasePixie and EraseAllPixies^t ,&a(ti i^j; ?.^ii^.iu^niX:- in m-rA 



S<>tBark Rrmind2 f$6F62) " 

Draws a packed supw hi-res screen (filetype PNT/$O00O) on the current drawing scTeen. You can create this kind of 
picture by packing a super hi-res screen with PackBytes, or using one of several IIGS graphics conversion utilities 
that are available, or by saving an 8/ 1 6-Paint^" picture as a scre^ The ha£Klle is left unlocked. 



Exaii^)les: 



Parameters: 



Errors: 



SetBackground2( Background, Flags ); f>1f)is&}itKK~t - -^i-) ^»?= 

TOOLBOX(98, 111 : BackgroundH%, BackgroundL%, Flags% ) v .*,.- 
Background (iMig) - handle to the packed screen *'} ^'q 

Flags (word) - list of options: '-mii ■^•mt-^^^ - > mfs--^-' 

- normal (like SetBackground) 

1 - pixels and SCBs only (no palettes) for QuickWipe or VBWipe 

2 - ready to fade in with QuickFadeIn or IncrFadeln lis^lS.? 
memory manager eiTOTS - ' ■safjJim' 
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Library Management Tools 

Tools used in loading and using picture libraries. 



1 



Parameters 



LoadLibrary f$2B62> rb-rwfl : ;-j u ? 

Retrieves a DrawTools picture library from the disk and returns its library ID number. -^t.-. ■/ ' 

Examples : LibID := LoadUbrary( path, SeqLibNum, packed ); ^ 

TOOLBOX(48,43 : 0,PathH%,PathL%,SeqLibNum%,Packed% ; LibID% ) . 
path (long) - GS/OS path name pointer 

SeqLibNimi (word) - logical number tor pixie sequence commands (else just 0) . . . t ■ i: ■ 
Packed (word) - bit 15 - TRUE if the library is packed with PackBytes ; n-jm^M ■' • ' 

- bit 14 - TRUE if GenAIIMasks should be called before library is used vj^;*'/ v ; ^ ' ; 
LibID (word) - the ID numba- tor the library cii«:/i » 

$6201 - too many libraries loaded (current limit is 24) : ;>-t:!> .'Vt.-. ' • 

$6202 - SeqLibNum is out of range «[■- ^-^tu? 

GS/OS and Memory Manager errors 

TTnlnadLihrflrv <$2E62> 

Deallocates a library loaded with LoadLibrary. Normally, DrawShutDown automatically unloads all Hbraries. 
However, this tool allows you to manually discard a library you no longer need without shutting down DrawTools. 
Exanq^les : UnloadUbrary (UbID); 

TOOLBOX( 48, 46 : UbID% ) ■*> 
Parameters : LibID (word) - the ID of the library to unload 

Errors : $6203 - invalid library ID number 

$6204 - flie library isn't loaded f * X 

Memory Manager errors 



Errors : 



Sct U brary 



ii<-aJ34^~-": -.so*.* -^j. -^fi^ 



: ■> 



Makes the specified hbrary the current one use with the drawing or animation tools. 
Examples : Setlibrary( LibID ); 

TOOLBOX( 48» 44 : UbID% ) 
Parameters : LibID (word) - the ID of the library to make current 

Errors : $6203 - invalid library ID mindwr 

$6204 - the hbrary isn't loaded 

Memory Manager errors 



GetLihrarv ($2D62) . . > Jv a^ziS^fr^ 

Returns the library id of the current library. ( :0 ; 8? .%Q ;XOSL^X>T 

Examples : UbID := GetLibrary; (tnow) m?i^1»tii'ia?<' 

TOOLBOX( 48, 45 : 0; UbID% ) say=.i 
ParametCTs : LibID (wcml) - the ID of the current library (-1 if none) 

Errors : none 
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J Animation Tools ^ 

Tools used in animating objects & handling animation sequences. 



Fine Pixie Data Record: 

0,1 - X Vector Low (word) 
2,3 - X Position Low (wordj 
4,5 - X Vector Hi (word) ^i^Jin^ 
6,7 - X Position Hi (word) 
8,9 - Y Vector Low (word) 
10,1 1 - Y Position Low (word) 
12,13 - Y Vector Hi (word) 
14,15 - Y Position Hi (word) 

16 - Index (byte) 

17 - Status (byte) 



Coarse Pixie Data Record: f^^jj^^^fi , 
0,1 - Vector (word) . ^n... i.s. 4*:^: : : = 
2,3 - Position (word) j. ii^iJ "^.Cfdi^ 

4 - Index (byte) . ; if ,?t> )X0.5'.>.:«ri 

5 - status (byte) %R;>j - <^a>'! 

Simple Pixie Data Record: i**, ' 

- Index (byte) ^ i utS 

1 - Last Frame (byte) - {tmsv^"- ' ''^--■.O 



When you ammate a pixie, the new pixie position is calculated by adding the vector value to the position 
value, resulting in the new position. For example, a fine pixie with an x vector of 1 (hi 1, low 0) and an 
original x position of 10 (hi 10, lo 0) will move to x position 1 1 the next time it is anixnated. 

Parameter Bytes Following Byte jt* Uxv? - / ■ * 
new status (byte) 

X & Y vectors to add to currait vectors (4 words) 
new direction (word) v 
new X & Y words (4 words) 
new Y words (2 words) 

new X words (2 words) ' X^,jf_ -fe .. 

LoadUbrary logical numbo- (word) . sS'.f:^, • / 

position to resume at (byte) ivv^J'--:^ «vin ' 



Sequence 


Description w ^^x^a, . 


Byte 






0...31 




picture to use in current library 


32.. .247 


reserved 


248 




change status byte 


249 




change fine pixie dir relative 


250 




change coarse pixie direction 


251 




change fine pixie direction 


252 




change fine pixie y direction 


253 




change fine pixie x direction 


254 




change library 


255 




end of sequence 


P 


For simple pixies, any negative byte (128 



iggerj IS consioerea an ena oi sequexKc cummHiiu. - «- y-: 
NewPixie f$3A62) 

Returns a number of a pixie that's not in use. When allocating several pixies, remember to use SetPixie after each 
NewPixie, OT NewPixie will return the same numb«- each time. -1 is returned if no pixie is free. 
Examples: MyPixieNum := NewPixie; -.i^-^^i 

TOOLB0X( 98, 58 : 0; MyPixieNum% ) .^^M te^ns-v V 1:. .- ■ ^ .r^ : 

Parameta^ : MyPixieNum (word) - the pixie nund)er(0... 15) .f»TekJ:^>= *Th C . ■ 

EiTors : none . M )r'MtJr<ri 
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ClearPixie f$3B62) iU^l^^' - 

Deallocates the specified pixie table position. ^ ^Amnia: mapst^ »> J*:*: > a 

Examples : ClearPixie( MyPixieNum ); ^ ^tB^TTi V^xi^^H 

TOOLBOX( 98, 59 : MyPixieNum55 ) " y^MJ&>'' 

Parameters : MyPixieNum (word) - the pixie number (0... 15) --^ --.^v 

Errors : $62FF - the pixie number is out of range, or the position is already free ^ 



SetPixie ($4E62) 

Sets up a pixie for use. If that pixie already exists, the old pixie is overwritten. ? 
Exan^les : SetPixie( pixnum, pixiedesc, pixieptr ); 

TOOLBOX( 48. 78 : pixnum%, pixiedesc%, pixieptrii%, pixi*^trl% J 
Parameters : pixnum (word) - the pixie numbw (0.. 15) ■ ■ 

pixiedesc (word) - description of the pixie: — ■'■' > 

bit 15 - pixie visible (TRUE) or invisible (FALSE) 
bit 14 - pixie matted (TRUE) or not matted (FALSE) 
bit 3-13 - reserved, set to 

bit 0-2 - pixie type (0=sinq)le, l=coarse, 2=fine) fS^S-^/' ^iU-J^h 

pixieptr (long) - pointer to the pixie data record ^ Jm^Jp-'*^^ ;9f> &i. • 
Errors : $62FF - pixie number is out of range ^ ■ j:i^*kie--r''j ■ 

GetPixie f$4F62) ^"^ a^a !Kt*^a* aisie i^i iHC-*? 

Returns a pomter to the specified pixie's data record. 
Examples : PixiePtr := GetPixie( PixieNum ); 

TOOLBOX( 98, 79 : 0, 0, PixieNum%; PixiePtrL%, PixiePtrH% ) '^^M^Il.J- 
Parameters : PixieNum (word) - the pixie nunU>er ^^'^ "'^ ■'-■'^ 

PixiePtr (long) - pointer to the pixie data record i*l«£^ jWJiilleJfWI - 
Errors : $62FF - pixie number is out of range U >XOff JOOT 

SetPixieSeq f$2A62) 

Assigns the specified animation sequence to a pixie; any old sequence is overwritten. The sequence index (ii 
pixie data record) is Qot changed. 

Examples: SetPixieSeq( PixieNum, LiblD%, SeqPtr ); . u 

TOOLBOX( 98,42 : PixieNum%, UbID%. SeqPtrH%. SeqPtrL% -w*. -Jf /i t - 

Parameters : PixieNum (word) - the pixie number 

LibID (word) - the delault picture library 
SeqPtr (long) - pointer to the animation sequence 

Errors : $62FF - pixie numb^ is out of range 



; I- rA - 



GetPixieScq($5062) 
Returns the pointer to a pixie's animation sequmce. 



Examples : 



Parameters 



Errors : 



SeqPtr := GetPixieSeq( PixieNum ); 

TOOLBOX( 98, 80 : 0, 0, PixieNum% ; SeqPtrL% , SeqPtrH% ) 
PixieNum (word) - the pixie number 

SeqPlr (long) - pointer to the animaticHi sequence 3ifJ \ 

$62FF - pixie number is out of range 
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HidePixie ($5262) 

Stop drawing a pixie on subsequent animation calls, but continue animating it as if it were visible. 
Examples : HidePixie( PixieNum ); ^ lais^nm'^^ ttMXt'htsi'* = 

TOOLBOX( 98, 82 : PixieNum% ) - jTms^Hitnr-M : O?. M iCln n 

Parameters: PixieNum (word) - the pixie number —^u^^i - i'o-^-iif^^ . r i. 

Errors : $62FF - the pixie number is out of range jq -^^jdmnv: m'vr^ ^vi - "'^'^i ' -^ 



Sho^yPixie ($5162) rw ^ s» «Xpi| bio Rsiai x^''-' 'i* ^' 

Draw a pixie on subsequent animation calls. -w^tx^ .rmjsnwj )i;-ii^fc£ 

Examples : ShowPixie( PixieNum ); ^ -^^.^^-^-^.j . ^e^v jxOHJOOT 

TOOLBOX(98,81:PixieNum%) ajjq w*i - ^tJ^--. — ^ ■ - 

Parameters : PixieNum (word) - the pixie number lyvia^^^ - (bm*; 

Errors : $62FF - the pixie number is out of range .^Hi^i, ^LsJ^ - ti ric 

DisablePixie ($2862) i ,?a^OTt*^'' ^^V* siJ"^ - ^^'^^ 

Stop animating a pixie on subsequent animation calls. q ■k^so^ki ■ «(fs^ ^ q 

Examples: DisableP!xie( PixieNum ); laetlo jt-o si ■ Wis^ ■ . 

TOOLBOX( 98, 40 : PixieNum% ) 
Parameters : PixieNum (word) - the pixie number 

Errors : $62FF - the pixie number is out of range Ui3l!fi j ^ii'^^'l- ' ' 

..■,-:r^v fi*<sfc e'-"^ix;'{ ; V'?^-!^ '-^^ v^^i - « . -.' V 

EnablePixic ($2962) /> .g : <^ jX^ja - 

Animate a pixie on subsequent animation calls. - i r. -■■^ - (^now) ^Hwx; , »i.->.s^ . ' 

Exanqiles : EnablePixie( PixieNum ); : ^^x*^ 

T(X)LBOX( 98, 41 : PixieNum% ) ttKt »; twi^is® a^^'j ■ H^.'i^^ ■-. 
Parameters : PixieNum (word) - the pixie number 
Errors : $62FF - the pixie numbw is out of range 

AnimatePix ie ($5362) 

Animate a single pixie one picture along its sequence. Unlike Animate, you will have to use SetUbrary to select 

the picture library for the pixie. The drawing positi(»i for the drawing tools is unaffected. 

Examples : AniinatePixie( PixieNum ); ^w*^ - r; 

TOOLBOX( 98, 83 : PixieNum% ) > . (i.-^; t 

Parameters: PixieNum (word) - the pixie number t^'^^^ 

&Tors : $620C - Command for a diffej-ent kind of pixie (disables pixie) ^i- . , ■ 

$620D - Undefined command in sequence (disables pixie) 

$620E - Pixie doesn't exist 

$62FF - Pixie nimiber is out of range tSt3^^iii^ . '5 > " ' ' 

SetLibrary enors ireiiamSafi* *'9i»i?if ^ n' c^iavr. ■y'^: x 

Animate ($2762) 

Animates all of the pixies one picture along their sequesices. The cowing positicm for the drawing tools is 
unaffected. ^un i&Q m its3«i4» a^:^^, T-t^df 

Examples : Animate; 

TOOLBOX( 48, 39 ) 
Parameters : ntme ■ 
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Brors : 



$620C - Coimnand for a different kind of pixie (disables pixie) 
$620D - Undefined command in sequence (disables pixie ) 
SetLibrary orors 



ErasePixie ($6B62) 

Erases the specified matted pixie wifli the corresponding contents of the shadow screeaa. 



Examples: ErasePixie( Pixie ); 

TOOLBOX(98, 107: Pixie%) 
Parameters: Pixie (word) - the pixie number 

ErrOTs: $620E - Pixie doesn't exist 

$621 1 - Not a matted pixie 



$62FF - Pixie number is out of range 



(J ■mA'i fits bHiif-f ft3yT?£v^r>,0.C >^i:ti^vi 



EraseAllPixies f$6C62) 
Erases ail enabled, matted pixies. 
Examples: EraseAllPixies; 

TOOLBOX(98, 108) 
Parameters: none 
EiTOTs: none 



if: MYKOH.'/i'iai' 



.1^ 



DrawTools 3.1 



Screen Tools 

Tools involving the screen, including those involving shadowing and the SCBs. 



CLSt f$3462t 

This tool acts the same as QuickDraw IT's ClearScreen. 
Examples : CLS ( ColourWord ); 

TOOLBOX( 48, 52 : ColourWord % ) 



Parameters : ColourWord (word) - word to fill the screen with \,^s^,^ i * '^^ 

Errors : n<me 

t Before System 6.0, ClearScreen would not clear the shadow screen; CLS works fine on older systems. 



QiiirkWipe f$lC62) 

This tool copies the shadow screen to the main screen. 
Examples : QuickWipe; 

TOOLBOX( 48, 28 ) 
Parameters ; none 
Errors : n<Mie 



0*»Ofo 



T ■ 



VBWipe ($3562) 

This tool copies the shadow screen to the main screen using a "Venetian blind" effect. 
Examples : VBWipe; 

TOOLBOX( 48, 53 ) 
Parameters : none 
Errors : none 



Fad«>Done ($4Cfi2) 

Returns TRUE if a fade is finished fading. In the current version of DrawTools, all fading occurs during the In/Out 
call; future versions will fiide during the FadeDone calls to allow animation to continue during the fading process. 
For compatibility, always have a REPEAT... UNTIL FadeDone (or the equivalent in your language) immediately 
after using a fade tool. 

Examples ; dOTe:= FadeDone; ^^''^ ' 

TCX)LBOX( 98, 76 : 0; done% ) 
Parametral : done (word) - TRUE if the last fade has been conqileted 

EjFors : none 



OuickFadeOutfIn ($16/1762) ^ . ' 

Fades the colours in the first eight palettes to black, or restores them to their (wiginal values. The upper eight 
palettes are used to store the original palettes. 
Examples : (^ckFatieinf rate ); 

TOOLBi. { 48, 22 : rate% ) 
Parameters : rate (word) - # 60th's of a second between INCs/DECs 

Errors : none 
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IncrFadeOot/In f$18/l962) 

Fades the colours in the first eight palettes to red, then to black, or restores them to their original values 
("incremental fade"). The upper eight palettes are used to store the original palettes. .ti>HS^->^ .. 
Examples : InCTFadeIn( rate ); , .. y . . ... .j-.^a. !<X?T 

TOOLBOX( 48, 24 ) -' - - -S-asKWi ?ac4'-;3 - • 

Parameters : rate (word) - # 60th's of a second between INCs/DECs .sn>ff; ' ,f 

Errors : none 

ShadowOn ($1262) 

This tool enables the hardware shadowing of the shadow screen. If you opMi a new graiport (using OpenPort) with 
shadowing enabled, the port will be assigned to the shadow screen, njpao^ sili ■- {br^^^' ■■^-•A': 5 m ■ it.'. 

Examples : ShadowOn; 

TOOLBOX(48, 18) 
Parameters ; none 

Emirs : none i.X^^J~.^k. .. K ' : 

ShfldowOff ($1162) 

This tool disables the hardware shadowing of the shadow screen. If you opm a new gra^xirt (using OpMiPort) with 
shadowing disabled, the port will be assigned to the main screen. i# - tinr*) i^fl ' >;i ■-■ ■ :-' 

Examples: ShadowOff, ^*v* w^ii^is^ ffji!r>*>£ftrdi 

TOOLBOX(48, 17) tM^awiJ ^ «^ .i«*B - tw3%v^ Mw?'jr«i^e 

Parameters : none vwai-a - < i-- 

Errors : none 

■ - - ■ ■ " • ■ i^Jn^^i ^H75i--i>-. 

WaitVB ($1362) 

This tool passes time until thebegiiming of the next vertical blanking period (1/60 to 1/30 of a second). If you erase 

during a vertical planking period, you will have less flicker in your animation. 

Examples : WaitVB; - ^ >XO*L.^-0-i 

TOOLBOX( 48, 19 ) . ... :^tft - f*;?«vr * ^« . . . m. 

Parameters : none flflttikBws?? Isri - (iKKaw) SftSif 

Errors: none - tWff") Ta»*S 

WaitLine ($SK62) 

This tool waits until your monitor is drawing a particular line. Use this to reduce flicka- when you are drawing by 
waiting until an object is drawn on the monitor before erasing it. 
Exanqile : WaitLine( line ); 

TOOLBOX( 98. 94 : line% ) 
Parameters ; line (word) - line number to wait for, 0.. 199 

if line < 0, line is treated as 

if line > 199, line is treated as 200 (same as WaitVB) 
Errors: none 
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SetBorder f$lF62) -Smmtl. .nl' ^i'C vi;^ - . 

This tool sets the colour of the screen border. t^J* .',-m 'V ■'.>> %;r; «i- «. ■■- .... 

Examples: SetBcB-der( Colour); fvm<aif^s tjqiiHf r 

TOOLBOX(48,3I :Colour% ) ffa?i^>^lT#ia 
Parameters : Colour (word) - the new colour (0... 15) as in the control panel /Ofi_iCK 

Errors : none. /SU'^^OHl sE4f«w^i ^s-^isks s ay ?' M^i^ % ■ ftf?.>^v . m6j ; . ' / 

-.- 

GetBorder f$lE62) 

This t(K)l returns the current colour of the screen border. 

Examples: Colmu- := GetBorder; l^kidh li^ - h ' 

TOOLBOX( 48, 30 : 0; Colour% ) " -■'bfi)&. jmv- bisrf ^[.^ifi^ ^ : .^1 

Parameters : Colour (word) - the colour (0... 15) as in the control panel.. ^ i<»*riK*^ '^r .h^ktert' > -ij-.: 

Brors : none . jSOv^ie^ii' ■■ -y.'ji-.f-f 

SetSCBs f$3662) 

This tool sets specific bits in the SCB's for a range of lines. This tool should not be used to change the interrupt bit 
while the SCB interrupt handler is envied. 

Examples : SetSCBs( linel, line2, BitsToSet ); .U'' *.(,i.x Oi^ ■ 

TOOLBOX(98,54:linel%,line2%,Bits% ) .. .-^ vn^n-ii ^Mi^a^ h : 

linel (word) - first bound line -t hwjgiaia ^ Ui* fiaq -r^ ,b3irf«sfAb .^^.w-r-,*. 

Iine2 (word) - last bound line .=j?t.'»*«r!ihao'fe. : ^-■•s^:^.: 

BitsToSet (word) - mask of bits to set (l=set bit) ; v? ^OS.JoOT 
none w^fi ■ --irtMsw.'-i^.'f 



Parameters 



Errors : 



ResetSCBs ( $3762) 

This tool resets specific bits in the SCB's for a range of lines. This tool should not be used to change the interrupt 
bit while the SCB interrupt handlo' is enabled. 

Examples : ResetSCBs( linel, Iine2, BitsToReset ); r^s^, iftw .bos^ s&rto^ ^v.- u - i -^.r .■- 

TOOLBOX( 48, 55 : linel%, lme2%, Bits% ) :«yttf.W ■ , ; 

Parameters : linel (word) - first bound line i n y^h^J^^JfCP 

line2 (word) - last bound line \&vy^ ...^-^ 

BitsToReset (word) - mask of bits to reset (l=reset bit) r-" 

Errors : nme 



«i ...... ■-; -■ -..-.-.^ .... d XifilK&TB tisiiV !,'*«; -n.^-V 

L MMf .0 - U 

(fiV>u. si«l,^l -aaHn 
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Scrolling Tools 


i 




Tools to scroll portions of the screen. 





The Format of a Scroll Record: 

0^ oftset (word) 

2^ width (word) 

44 fillpic (long) 

8,9 first (word) 

10,11 numblocks (word) 

12-15 reserved 



byte offset into fill picture 

width of the picture in bytes (eg. 160 for a screen image, 12 for DT pic) 
ptr to picture to fill with , , ^ ' „ . . ' 

first (top) screen line to scroll )'/x>^ *i ' 

number of 8 line blocks to scroll , TJ^ . . . 
must be U ^ j ■ _ - t t - . 

ScrollLinesL ($30621 

This tool scrolls the indicated lines one block (2 words) to the left, and fills them from a specified picture. The offset 
is incremented by the width. 

Examples: ScroUUneslX ScroURec ); • i» - .V' 

TOOLBOX(48,48:ScrolIRecH%,ScrollRecL%) *';^?rjr,'*"''^ ^ 
Parameters: ScrollRec (long) - pointer to the scroti record ^i- JfO'-i K>\^T 

Errore: $6206 -first line is out of range .^^^^^ ■y,*r=^)^35 ^y..^.-. 

ScrollLinesR ($3162^ 

This tool scrolls the indicated lines one block (2 words) to the right, and fills them with a specified picture. The 
offset is decremented by the width. 

Examples: ScrollUnesR( ScrollRec ); . 

TOOLBOX(48,49:ScroURecH%,ScTollRecL%) Zl^J-j' 
Parameters : ScrollRec (long) - pointer to the scroll record v?j: i4, » js 

&rors: $6206 - first line is out of range ^. , , ^ ! 



Nt^e : Tlie current version of ScrollLinesR will not work properly if the first line is,0. 



ScroULinesU ($3262) (not available veO 

This tool scrolls the indicated lines one block (2 words) to up, and fills them with a specified picture. The offset is 
incremented by a row of blocks 



ScrollLinesD ($3362) (not available yet) 

This tool scrolls the indicated lines one block (2 words) to down, and fills th^ with a ^)ecified picture. The offset 
is decremented by a row of blocks. " 
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Palette and Colour Tools 

Tools that change colours and manipulate palettes. 



SetPalette f$lA62) ' J 

This tool sets the palette for a range of screen Imes. ^ ^ 

Examples : SetPalette( imel, line2, palette ); ' ' ^^^'^ ^'^^J;- 

TOOLBOX{48,26:lmel%,lme2%,palette%)'^^^"^ ^ /"^ " ! 

ParametCTS : linel (word) - first bound line ^.^ ^ lir' ' 

line2 (word) - last boimd line '* 
palette (word) - new palette number for lines (0..15) 

Stots : none (no range checking) ir - > . 

-^WJ'mj .^..t-vi W*? Ctf (afar^V V 1 ixlW Wl^ !i::?-Oi^tV .Till ^ ^ ::; t-- J 

0.tPaiette ($3862) .-^.u... ^^'"^'^-Z 

This tool returns the palette assigned to a particular screen Ime. ' ''^ . \ - .^^7 . ' 

Examples : palette := GetPalette( Ime ); ^ , « » 

TOOLBOX( 48. 56 : 0. line% ; palette^ ^""^^^ f 
Parameters ; line (word) - which line to check ' ^ 

palette (word) - palette number for that line (0...15) 

FadcPal f$lB621 - ;Jle*3s i-^/ / 

This to<il dims the source palette colours and stores them in the target palette. ' J^^l^Ll" ' 

Examples ; FadePal( sourcepal, targetpal ); , 

TOOLBOX(48,27:sourcepal%,targetpal%) ; f^f^ 

Parameters :s ourcepal (word) - palette to fade (0...15) ^ F«a ■ 

targetpal (word) - w*ere to store the faded palette (0...15) . , . 
&rors : n<Hie ' : 

UnfadfPal ($1P62) 

This tool brightens the source palette colours towards those in the target palette. The colours are stored in the 
palette. - ■ . . 

Examples : UnfadePal( SourcePal,TargetPal ); 

TOOLBOX( 48, 29: sourcepal %, targetpal %) SAMSt f% ' 

Parameters : sourcepal (word) - palette to brighten (0...15) m*lV^ .fjy^ 

tarsetpal (word) - palette to compare with (0..15) 
Errors : none 
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SetColour ($4062) 

Combines the red, green and blue values into a colour word. 
Examples : 



Parameters 



Errors 



word := SetColour( red, green, blue ); '^m{^<l^g^H tatiiii } 

TOOLBOX( 48, 64 : 0, red%, green%, blue%; word% ) M VrOfEJOfJT 
word (word) - palette colour word 4j . '^stjw ) 

red(word)-ainountofred(0...15) ^rt«aRi*,(M..O - (IrtCtVi iMir^-' 

green (word) - amount of green (0... 15) fvw rv»*ifei;» fcrr^ flufe -'hf.**') l vx> 
blue (word) - amount of blue (0...15) ' • : 9^ . (t^_ *) ^j^^ 

none. Bad values result in a meaningless colour word. Ji^r.'Vi - 



SetColPercent ($4162) ' '^.ta ^aalli an; - ^ :ij\a?^'«liXiUs^ 

Combines the red, green and blue percentage values into a colour word. -(^ jT/biasiiJ ^. W^'-XJ :t^m&?^- ^ ■. ' 
Examples : word := SetColPercenl( red, green, blue ); ^a^^Aab -f--) %iiti(i'jmii^ . ;: 

TOOLBOX( 48,65 : 0,red%,green%,blue%; word% ) umJ,/^ <«> :^A^^[i>~^is^: 
Parameters : word (word) - palette colour word {fshixsK t>3} :(i&?>ft3 .0 am^-' A^u 

red (word) - percentage of red (0...I00) ^?5if(»k;T'S>a3?S luol •=?f*'.V.:*.^^: : 1^ 

green (word) - percentage of green (0... 100) 

blue (word) - percentage of blue (0...100) 
&Tors : none. Bad values result in a meaningless colour word. (kdiS^^j, - V-iZh: 

Elaboration: A few example RGB percent values (extracted from ACM SIGGRAPH '89 course notes): 



Gold 


78,61, 16 


Old (dark) gold 


78, 43, 10 


Platinum 


83, 79, 56 


Silver ^^j; . (tr 


J. 81.82.70 


Antique (daric) silver 


53, 52, 47 


Steel 


55, 62, 59 


Copper 


97, 60, 28 


Brass 


69, 63, 23 


Iron 


18,7,6 


Sunlight 


100, 96, 92 


Moonligh 


75, 81, 100 


Naples Yellow 


100,66,7 


Cadmium Red (Ruby) 


89, 9, 5 


Brown Madder 


86, 16, 16 


King's Blue 


1, 57, 76 


Indigo 


3, 18, 33 


Emerald Green 


0, 79, 34 


T«Te-vefte 


22, 37, 6 


Ivory Grey 


16, 14, 13 


Lamp Black 


18, 28, ,23 



■rm'oci' ^ sir'-; 

colour := FindColour( numcol, palette, colourWord ); 
TOOLBOX( 48, 66 ; 0, numcol %, palette %, colourWord %; colourWord% ) 
numcol (word) - 16 if 320 mode, 4 if 640 r ; s?s^£j*^ ( fcag^*^^., 

colour (word) - the colour number of the closest colour 
palette (word) - the palette to search ^ ( ^»(:- 9i3»il^ . 

colourWord (word) - the palette colour word to match -^.^^ 
none 



FindColour ($4262) 

This tool search the specified palette for the closest colour to the one requested. 
Example : 

Parameters : 
Errors : 



■r.ifs:' . ■- 

■ 'iv 



DrawTools 3.1 



4a 



BlendColour ($5F62) 

B lends two colours together to form a new colour. 



Example : colour ;= BlendColour( weight, coll, col2); ^ >*K>fr>'>^j'^^'' tvir; <■ 

TOOLBOX( 98, 95: 0, weight%, colt %, col2%; colour%)^^^ fXOi^.KKlT 

Parameters : colour (word) - the new colour word *5 ■ ij^^-^'u'j ,'r>>fl 

weight (word) - 0..16, amount of second colour to mix in'^s* itn-->*?) y,". 
coll (word) -the first colour word , » > ihvr^)m^'n.^ 

coI2 (word) - the second colour word ^' ' --iJ^H V> Mt^'^w? s^'-^^"^ 

Errors: $62FF - weight is out of range .isiet *«5Uv fe*S :Ar.'fi 



"Tyi Elaboration: Some BlendColour Applications: ^SsU^tl .Jmtiir.C-.. } ■ 

Y (l)Blending:colour:=BlendColour(weight,coll,col2); J*/ is3»l^is^?»q soM Iijbk tsitjTf, at? .c. t ' 

(2) Bleaching (eg. for distance): colour := BlendColour(distance, col, backgroundcol); 

(3) Anti-aliasing; (a) colour ;= BlendColour(amount in pixel, colour, backgroundcol); (b) coiourNum := 
FindColour( 16, 0, colour); {for 320 nsode} 

(4) Saturating: colour ;= BlendColour(how much to saturate, colour, SOF(X)); - >- ^ 

FadeColour f$6062) Sgam-m^^-- « Hs;»sf! ■> ;,s*v 

Fades or brightens a colour. 



Example : colour := FadeColour(oldcolour, di^rence); 

TOOLBOX(98, 96: 0, oldcolour% , difference%; coIom-%) 

Parameters : colour (word) - the new colour word 

oldcolour (word) - the original colour word • -XM 
differmce (word) - (-15) to (+15), amount to change the colour by 

Errors : Nraie 



Elaboration: Some FadeColour Applications: ' >!.' ? 

(1) Darken colour: colour :=FjuleCoIoui<oldcoIour,-l); .'^ 

(2) Brighten colour; colour ;= FadeColour(oldcolour, -i-l); ,? 
-4 .(»V .0 



I 



FlndPalette f$6162> 

This is my "mini Palette Manager" tool. Returns the colour numbers for the entries in the current palette which 
most closely resemble the colours that you expect in that palette. Especially useful for NDAs, where you don't know 
what colours will be on the screen. FindPalette only recognises pure colours in 640 mode (not dithered colours). 
Example : changed := FindPaIette( colours, palette ); 

TOOLBOX{ 98, 97: 0. coloursH%, coloursL%, paIetteH%, paletteL%; changed%) 
Parameters; changed (boolean) - True if the colours have changed since last FindPalette ?k«>"v 

colours (long) - address of a list of 16 colour numbers corresponding to the colours in the palette 
palette (long) - address of palette (a QuickDraw II colorTaWe) of desired colours 
Errors : ncxie 
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Interrupt Tools 

Tools Involving SCB (or Horizontal Retrace, or Scan Line) Interrupts 



Format of a SCB interrupt task header: 

0-3 longword TaskPcr Use by the Intorupt Tools; do not modify 
4-5 wofd Scan Line Line number of the task 

6-7 \M3fd SigWord sigmUure wOTd; always $D44D 

8-A 3 bytes EntryPt task entry pointer 

Designing an Interrupt Ta^ The task must be a long subroutine (fliat is, aid in an RTL instruction). B and D 
registers must be preserved, but other regist^^ (A,X,Y J*) need not be. A task may have two or more headers if it is 
to be used on two different screen lines. Becwise DrawTools is non-reentrant, nevw call a DrawTools from a task 
unless your are sure the main program is not using DrawTools at the same time. • > - 

IMPORTANT: (1) I have no idea why, but if you use tbs SCB interrupts, make sure you unload DrawTools before 
your program quits or the next program that runs will crash; at least, it h^pens with Merlin 16+ and EXE files -> it 
crashes during a Misc. Tools _GetVector call in DrawStartup. (2) When the interrupts are enabled with 
EnableSC Bints, do not switch the processor into emulation mode (e=l) without suspending interrupts (with SEI). 
The patch I placed on the interrupt manage is not designed to handle ennilati(» mode IRQs. 

E o ab l eSC PInt s ($4A$2 ) 

This tool must be used before all other SCB interrupt tools. Patches the system iBtemipt manager to use my SCB 
intmupt handle. 

QuickDraw SCB interrupt use is suspended. The task list is cleared. 
Examples : &iableSCBInte( enable ); 

TOOLBOX( 98, 74 : enabled ) 
Parameters ; enable (boolean) - TRUE if interrupts are to be eaiabled 

EzTOTs : none i 



SetSCBInt f$3C62) 

Installs a SCB intemipt task for the given screen line. AutomaticaUy subtends all tasks until the next 
ResumeSCBInts. 

Exan^les : SetSCBInt( TaskPtr ); 

TOOLBOX( 98, 58: MachineLgH^, MachineLgL% ) 
Parameters : TadcPtr (Icmgword) - pointer to the task header 

Enors : $6205 - Ta^ signature isn't $D44D 

$6206 - The scre^ line is out of rwge 

$6207 - A task already exists for that line 



DelSCBlnt ($3D62) 

Deletes a SCB interrupt ta^ Automatically su^>»]ds all tasks. 
Exanq)les ; DelSCBbit( Taskline ); 

TOOLBOX( 98, 59 : Ta^cUne% ) 
Paraiihsters : Taskline (integer) - screai line of the task 

&T(vs : $6206 - The screen line is out of range 
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$6207 - A task doesn't exist for that line 



ni 



ClrSCBInts ($3E6^) ^ ^-mitr»o-l sf^^oT i 

Deletes all SCB intemipt tasks. Automatically suspends all ta^. ™. -— ^ * 

Example : ClrSC Bints; 

TOOLBOX(48,62) r^tsSk&tfi. i^j^i f^imcHm r, o 

Parameters : none ;^i«s»T li^fftieaiJ ajft ¥ i aetJ iS^ml ■. yi^^y 

Errors : none ^ifi -b^hsru - ssisi ? jssfwi - -■- v 

ResumeSCBlnts ($3F62) 

Waits few the next vertical blanking period and resumes executing all SCB interrupt tasks. ^ v.-; 



Example ; ResumeSCBlnts; 

TOOLBOX( 48, 63 ) 
Parameters : none 

Err«^ : $6208 - SCB interrupts not enabled 

:?^jls«i sk* $62FF - no tasks to execute - , sjet fei Jod »f**''^?rt^ i (1} - '{'A^:. '-W 



I 
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Printing Tools „ ,, 

Tools to help assembly language programs write on the screen. 



Readv2Print ($56621 

This must be the first printing call in a new window (or graiiport). Gets a points to the current grafixjit, resets the 

margins to 0, and "homes" the QuickDraw pen. 

£xanq>les : ~Ready2ftint ^ 

Parameters : None 

E™s: None xSkntH -^5*^:1;^.;.: 

SetLTMargtns f$5D62) 

Sets the left and top printing margins. Use Home to plat^ the peo in the top-left coniM- of the new margin settings. 
Exan^iles : -SetLTMargins #Left; #Top , . 

Parameters : Left (wcwd) - left margin, in pixels 

Top (word) - top margin, in pixels 
Errors : None j^'^fj. tri.i, ; ■ 

5(5) -fso ^nmif 'JS^oeOi ' -lt--. •■> k \. r 

Home ($5762) - v 

Moves the QuickDraw p^ to the left end of the first text line on the screen, like BASIC'S HOME. 
Examples : -Home . , oi 

Parameters : None 
Errors: None - 



HTab ($58621 

Moves the p^ the specified nund^er of pixels to the right of the left margin. 
Examples : ~HTi^ #Indeiit 

Paramet^ : Indoit (word) - number of pixels to indent 

Errors : Ntme 



VTab {%mZ ) 

Moves the pen down the specified number of screen lines from the top margin, based on the height of the currrait 
font. 

Examples : ~ VTab #NewIjne 

Parameters : NewLine (word) - new screCT line; 1 is the top line. 

Emn^ : $6ZFF - NewLine was negative or zero 
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Print ($5A62) 

Draws a Pascal string on tfie screm. 
Examples : -ft-int #str; ^mode ■ 

Parameters : str (long) - pointer to the Pascal string 

mode (word) - printing mode: ^-ivlRi^sw* t>i <4w>X \ 

bit 15 - TRUE if a carriage return is to follow printing ^ 

bit 7 - tab to next column of 64 pixels after printing 

bit 6 -clear to end of the line 'JM^Xi M-XiX.' ' 

other bits - reserved; set to ■ ^^-^ifw -^5*s g sf tU-> pibaa^i i^,,-' -^^i K-i-i^- 
Emirs : none ^^lO -i.uf^,/ ^tit '^T -r 

'ifs>>*' . -ri - ... - 

PrintHes (%5h62\ ^^"■'i 
Draws a hexadecimal value on the screen. 
Exan^>les : -IVintHex ^number, ^^mode 

ParametfTs ; numb^ (word) - the number to print iM'tS^.' iiJtJj 'Ui- 'i^;,. - 

mode (woid) - same as with Print ^"^i .^sastsm ?hh -^f ^ i-^.. .t-: i * 

Errors: none '?t>T^ ^^.xfJ* ^a^^^H j.^a-. ■ - 

Printlnt f$5C62) 

Draws a signed integer value on the screen. 
Exanq)les : -Printlnt ftauaixr, ffrnode 

Parameters: number (wwd) - the number to print '-^^ £v] - 

mode (word) - same as with Print :^ «9 adJ-trfiK-q.^wKl^^.r-'i -y 

Errors : none ' ' ' ' 
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Driver Tools 

For a general discussion on game and network drivers, including how to design them, see Appendix D. 



LoadPriver <$6D62) 

Loads a specified game or net driver into memory. 
Example: DriverPtr := LoadDriver( Driva-Path ); 

TOOLBOX(98, 109: 0, 0, DriverPathH%, DriverPathL%; DriverPtrL%, DriverPtrH^) 
Parameters: DriverPath (long) - the Pascal string pathname 

DriverPtr (long) - pointer to the drivCT 
EiTors: GS/OS errors 



UnloadPriver ($6E62) 

Unloads a specified game or net driver from memory. 
Exanqiie: UnioadDriver( DriverPtr ); 

TOOLBOX(98, UO: DriverPtrH%, DriverPtrL%) 
Parameters: EJriverPath (long) - pointer to the driver to unload 

ErrOTs; $62FF - unknown error while unloading 



Installs a game driver for the specified player. 



-vTjO<"^SS^ vrf ifi^u': -EaV.ii^i I'Jix aflt '-rir 
. _ '/YJ V .i fm!f_* - fa"*- ;il> ss*' :JW»^' 'mi 



Example : SetGameDriver( playerNum, driverf*tr ); 

TOOLBOX( 98, 99: playerNum%, driverH%, driverL% ) 
Parameters : playerNum (word) - 1..4, the player to use the game driver 

driverPtr (laig) - address of the game driver 
Errors : $62FF - DrawTools version is too low for this driver 

$620F - device number is out of range 

$62 1 - The device this driver operates can't be found on the GS 



A*5 It ■ '"^f f 



SctNetPriver f$6262) 

Installs a network driver so that remote game drivers can be supported. 
Example : SetNe(Driver( drivea-Ptr ); 

TOOLBOX( 98, 98: driverH % , driverL% ) 
Parameters : driverPtr (long) - address of the net driver 

Errors : $62FF - DrawTools version is too low for this driver 

$6210 - The device this driver operates can't be found on the GS 



.^■JCr? «*WJifi^»>5 i 1--" .'.-i - 



SendNetwork ($6462> 

Sends a message to the net driver and returns status information from the driver. The two parameters are used for 
both. 

Exan^le : SendNetwork( command, data ); 

TOOLBOX(98, 100: commandH%,commandL%,dalaH%.dataL% ) 
Paranwters : command (long) - address of the command; holds result afto* call 

data (long) - data for the command; data for the result 
Errors : $62FF - no net driver has been installed 
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Se ndNetwork commands: 

Notes: (1) Commands marked with an asterisk (*) mark commands called automatically by DrawTools when 

L required. (2) "Post" is used in the sense of PostEvent in the Event Manager: transmits a message on the 
network or to the driver. 

- no command fuse to poll the network) is-irf'jk-S" u ■ , ' 

1 - request the number of remote players if*««*^t .M- ■ -.a ii*<. 
*2 - request the pseudo game driver addrSvSs (returned in data) (used by SetNetDriva-)^ ' ^* ' * 

*3 - post a new local player {data=player#) (used by SetGameDriver) JCx'-T -''-j-^'^ 

4 - post a local player quitting (data=player#) 

*5 - post local GetJoy result (data^evice(bytel)^s(byte2),value(bytes3&4) (used by GetJoy) ' " 

*6 - post local GetFire result (data=result) (used by GetFire) 
*7 - post local StillFiring result (data=result) (used by StillFiring) 
8 - post abort game message (you can use it for whatever you want) 
*9 - init the net driver (used by SetNetEMver) 

* 1 - shut down the net driver (used by DrawShutDown) " . ^ , 

1 1-15 - reserved tor luture use 



own f-Oic-O 



16-1 23 - applicsitioa defined ^^JT 
124 -set address of wli»e to receive mcoming data (data=address) (for 125, ..127) . , ^. 

125 - prepare to transmit (data=player(low), number of blocks lobe sent(high)) 

126- block transmit(data=pointer to 256 bytes (a "block")) " '^^ 

127 - done transmit(data=^lay^ who should have received blocks) 

128 - driver will begin displaying status information on the screen (use DrawTools* Print tools) 

129 - driver will stop displaying status information 'fUij- y 
130-255 - net driver defined. With the Null Network Driver: --J^'"** ' ' 

130 - fake a new remote play^ (#2) beginning to play ^ 

1 3 1 - fade a remote player (#2) quitting " . . . .- ^ i.. -v 
>255 -reserved for niture use 

RestiJts returned by SendNetwork: 

Note: only (null event) or orors should be returned during a block transmit or an inft^rmation request, to avoid 
having to handle two things at once! 

- null event (nothing interesting happened) 

1 - abort game was received from a remote GS . , . y. - 

2 - a new remote player has started to play (data=player#) -^-'/-j 

3 - an old playo" has quit playing (data=player#) " , utisu Ui ■ ' 

4 - bad connection (can't find the network) . . ' " ' 

5 - bad rtetwOTk error 

6 - network full (already 4 players plajdng) _Z •s'' ^ «!mw<^« v 
7-15 - reserved for niture use 

16-124 - you received an applicaticm defined evait of same number (data=other information) 
125 - prepare to receive transmission {data=p!ayer(low), numbCT of 256 byte blocks (hi)) 

126 - received 256 bytes of data (data=handle to data) . . 

127- end ofdata(data=^layer who should have received data) .^-.^^,Amr.' .^^ ^ ■ 
>126 - reserved for mture use 
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GetJov ($4362) 

Returns the position of the joystick along one axis. Horizontally, left (-2) through right (+2); vertically, top (-2) 
through bottom (+2). There must be a 3 microsecond delay between GetJoy calls. 



Examples : 



ParauKta^ : 



Position := GetJoy( Device, Axis ); r. ^ , jvir>j 

TOOLBOX( 98, 67 : 0, Device%, Axis% ; 'l*osition% ) 
Position (word) - the joystick position, -2 ... 2 
Device (word) 



)V'<7m J?*Mi Hi TP*"! Ml.-;.; fit:-". 



- for mtemal joystick, or 1 ..4 for a game dnver 



Errors : 



Axis (word) - = horizontal axis ; 1 = vertical axis. 

- 23 - same, but for joystick #2 (device only) 
Axis value ANDed with 3. 
$620F - device number out of range 



GetFire ($4862) 

Determines which joystick fire buttons have been pressed (but not held down) since last GetFire/SlillFiring). The 
button addresses were taken from the November '90 issue of "8/16". 



Exan^les : 



Parameters 



) 



Errors : 



Buttons := GetFire( Device ); 
TOOLBOX( 98, 72 : 0, Device%; Buttons 
Buttons (word) - mask of fire buttons 

bit = I => button #0 is depressed 

bit 1 = 1 => button #1 is depressed 

bit 2 = 1 => button #2 is depressed 

bit 3 = 1 => button #3 is dressed 

bits 4-15 are zero 
Device (word) - for internal joystick, or 1 ..4 for a game driver 
$620F - device numb^ out of range 



StillFiring ($4D62) 

Determines which fire buttons are being held down, whether or not they were during the last GetFire/StillFiring call. 
GetFire does not need to proceed a StillFiring call. 



Examples : 



Parameters 



Errors : 



Buttons := StillFiring( Device ); 
TOOLBOX( 98, 77 : 0; Buttons% ) 
Buttons (word) - mask of fire buttons 

bit = 1 => button ifO is dqn-essed 

bit 1 = 1 => button #1 is depressed 

bit 2 = 1 => button #2 is depressed 

bit 3 = 1 => button #3 is depressed 

bits 4-15 are zero 
Device (word) - for internal joystick, or 1 ..4 for a game driver 
$620F - device number out of range 



J 



DrawTools 3.1 



56 



Miscellaneous Tools 



($2062) 



Returns the Quick Dispatch Table (QDT), a set of 16 JML instructions (64 bytes) to commonly used DrawTools 
routines. These are provided for assembly language programs that wish to avoid the overliead associated with tool 
calls. You must be in 16-bit native mode to execute the QDT routines. Jumping to a non-existed JML will cause 
unpredictable results, so check the toolset version before using GetQDT to ensure the JML's are available. 



Preparing a quick dispatch table: 

Draw adrl ; the quick dispatch table of 16, 

Draw48 adrl ; in ORCA/M use i4 



4 -byte JML entries 



vectoris 



sin .(isahi^ilji? 



adrl 

PushPtr Draw 
GetQDT 



Using the quick dispatch table: 
LDA #ThePic 
JSL Draw 

Register results after call: 
A - the result, if any 
X, Y,B,D- unchanged 
P - reflects the result, if any, else scrambled 



bbM are Uidi ^vasii^f emd y/ntf aj0< :ns6 sift ' 
t/i 5«a%j 0^ T?ft^-;VDl^ ^ m<j^ ct*^3(al ?.-::*y 

i- rttsmm -t* ! a 1 jiti 

. i & t. ?S'i; 



.11 - 



The vectors are defined as: 

Vector#l - DrawTools 3.0 - Draw 
Vector #2 - DrawTools 3.0 - Draw48 
Vector #3 - DrawTools 3.0 - DrawOn 
Vector #4 - DrawTools 3.0 - Draw480n 

Vector #5 - DrawTools 3.0 - AnimatePixie (errors returned in A) 
Vector #6 - DrawTools 3.0 - Rnd 
Vector #7 - DrawTools 3.0 - Odds 
Vector #8 - DrawTools 3.1 - WaitUne 
Vector #9 - DrawTools 3. 1 - ErasePixie (errors returned in A) 
Vector #10 - DrawTools 3.1 - save interrupt space 
Vector #1 1 - DrawTools 3.1 - restore intemqjt space 
Vector #I2-#16 - reserved for ftiture use 



( 



Vectors 10 and 1 1 backup DrawTools* direct page space. This allows you to call most DrawTools' functions from a 
RunQ task or another interrupt task. Alternately, you can use the scheduler. You will have to use these if an 
interrupt may occur during a DrawTools call: failure to do so may crash your program. 



Examples : 
Parameters : 
Errors : 



For Merlin 16 : -GetQDT #MyQuickDispatchTable 

MyQDT (long) - location to save the copy of the quick dispatch t^le 

none 
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.ti\^ «Sm© fi^*^ lo 'yrtii ads (tttWt -^3£Sj a^ffls-i s<ti 1'.mi!^ihv »di mot* **?-rvXi m vh.^-' .n " 

iw3'i-.J ritacjmcm io<6iisi .-* ■:- 

WorkCursort ($4662) / X^&^%t..J}Ta^m^ Jkns} 

Replaces the mouse cursor with the woric cursor . Currently, the cursor is a pair of gears. ■ 
Examples : WorkCursor (NumCalls) 

TOOLBOX( 98, 70 : NumCaILs% ) 
Parameters; NumCalls (word) - = animate on every StillWorking, n = every nth ' ■"' 

Errors: ntme C.-''' .'. 

t See WorkCursor2. '^it^-; '^M 9i a'^tm^^i' ->7.^-! >/, .^s 

WorkCursor2 ($6862) ^ewswJlfiiq&O^Osi^ ,^ior{ J/jo^^jprn «f^6^: -v.;. :;-. 

Same as WorkCusor, but works properly with acceloator cards. i^ - (^^ic^-' ■ ' 

Examples : WorkCursor2 (NumTicks) ^ ' (gnolj gJIs^Hr^:! 

TOOLBOX( 98, 70 : NumTicks% ) wema r.jts^rwst roj»2«» ^?.>'Si:' 
Parameters : NumTicksIs (word) - = animate every StillWorking, n = every n/60ths sees. 

Errors ; none 

StillWorkin ff ($4762) " " '''' 

WorkCursorAVorkCursor2 must be called first. Checks to see if the work cursor needs animating. Use InitCursor if 
you want to restore the cursor to an arrow. 
I J Examples : StillWorking; :HM yj^^.HJ^ : 

^■^'^ TOOLBOX( 98,71) -asi**^^ Tg^mo^ - ^^i^'^r^i ^) ' >• ■ i 

Parameters: none ':t:tp m ■ (tfoi^^ ^••(frT^yi 

Errors : none ■ ^-*'"^34t s « f - " 

Odds ($4462) ' ^'--^ 

Returns TRUE the given percentage of the time. Percentages of zero or less are always FALSE; percentages of 100 

or greater are always TRUE. This tool is accurate to about 2% . 

Examples ; Boolean := Odds( Percent ); l^C;!'^) 

"n^m' «iti B TOOLBOX(98,68:0,Percent%;Boolean%) * m f^m: ^ ' - '■ 

Parameters : Boolean (word) - die truth value ^-^'t 'i"'^ ? - ■ ' • 

PercCTt (word) - die percentage of the time to be true. -(a ^'-^vs-vi--: 

Errors: ncme ; 

■■■■*" ■ -■■■wtDv?? 1, : 

-..fix?!" 

RND ($4562) . ■-' ^- ; %m^t^m -iW^'r^^Pii^W^--^ ?v^?'^f:. -^-^ 

Returns a pseudorandom number between I and the specified limit. Limits of zero or less always result in zero. 
Exanq)les : number := RND( limit ); 

TOOLBOX( 98,69 : 0, limit% ; number% ) i ^-SsioH » S 
Parameters: number (word) - the random number, 1... limit S^V*. 

limit (word) - the maximum random number (1...32767) ^2* 3 

Errors : n<me ■ 



NnrmalRND ($6562) 
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Parameters 



Errors : 



Returns a normally-distributed, or "bell-curved", pseudorandom number betweai 1 and the specified limit. The 
numbers are more likely to come from the center of the range than from the low or high ends of it. 
Examples : number := NormalRND( limit ); 

TOOLBOX(98, 101: 0, limit; number) 
number - the random number, 1... limit 

limit - the maximum random number (1...32767) '- -v i .' • 

fio"^ .. .. . . . : , ivt ... . /Ki'tf SfHi 4Vr^ it^iui:*^^ -. . 

HLoad ($2F621 

Handle LOAD. Loads a specified file into memory and returns a handle to it. (For those who like avoiding all those 
GS/OS details, like me.) The handle is left locked, .Cir^ei'- >,x 

Exan^ies : DataHandle := HLoad( Path, FileType ); 

TOOLBOX( 98, 47 : 0, 0, PathH%, PathL%, FileType%; DataL%, DataH% ) 
Parameters : Path (longword) - pointer to the GS/OS pathname ^t^^^H rj, ■ ' 

FileType (word) - file type expected (ot for any type) ^ rsh> !^' -vrfi' ''^y - ■. - 

DataHandle (long) - handle to the file data - W 

Errors : GS/OS and memory manager errors (file busy errors handled internally) - 

$620B - FileType mismatch ^ , ^^.-^ .■ . ..^w. ..-.>y-^-' :.r....-%i^. 



HSave ($5462) 

Handle SAVE. Saves the contents of a handle in a file. If a new file is created, the file type is the same as the 
FileType parametCT, and the AuxType is 0. The handle is left locked, tjeiiwo «fJ Mi^:'^'' v-'V.-- . 

Examples : HSave( Path, FileType, DataHandle ); -t- .nTjJws? 

TOOLBOX( 98, 84 : PathH^, PathL%, FileType%, DataH%, DataL% Jg ; ' . 

Parameters : Path (longword) - pointer to the pathname M '.fi&.i«X!T 

FileType (word) - file type expected (or tor any type) , 
* type -1 is a special type; PNT/$0001, packed screen (used with S^Background) 

DataHfuidle (long) - handle to the data to be saved 
Errors : GS/OS and memory manager errors (file busy errOTs handled internally) 

$620B - FileType mismatch ^ I^^M-'t- 

BarGraph ($4B62) ' 
Draws a bar gr^)fa in a specified rectangle. The graph shows the percentage relationship between the " 
parameter and the max value in the graph record; values < 0% are treated as 0%; values >100% are treated as 
If the rectangle is larger vertically, the graph is drawn upward; if the rectangle is larg^ar horizontalty, it is 



value" 
100%. 
drawn 



rightward- 
Examples : 

Parameters : 



Errors : 



BaiGraph( GraphRec, value ); 

TOOLBOX( 98, 75 : GraphRecH%, GraphRecLX, value% ) 

GraphRec (long) - pointer to a gr^h record 

Graph record : 

0-7 Grajdi rectangle containing the graph 
8,9 ForeCol SolidPaiPat value (-1 for current pen pat) XrOT 
A,B Backed SolidBackPat value (-1 for current back pat) 
CD Max maximum value for the graph ;{ 
E-1 1 reserved reserved; set to -jsn^ 

ncne 



-■-J 
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GetMHz ($6267^ 

Returns the current GS speed to the nearest MHz. (Also adjusts GetJoy so that it will operate properly at the current 
speed.) 

Speed := GetMHz; 8» _ 

TOOLBOX{98, 103 : 0; Speed%) . is(»«&*-1 : ■■■ - f 

Speed (integer) - speed of the GS to the nearest MHz. r^wa v 

PrintWindow f$6A62) 

Sends a window, grafport or the screen to the printer. The Print Manager is automatically started, if necessary. No 
clipping is performed on overlapping windows. Also, you will need at least 32K free: PrintWindow saves the 
contents of the screen before showing the dialogs. . -^....^ ^ 

PrintWindow( WindowPtr, Options ); ' ' ' 



Examples: 

Parameters: 
Errors; 



Examples: 
Parameters: 



&Tors: 



TOOLBOX(98, 106: WindowPtrH%, WindowPtrL%, Options^) ^ T«5^< " - 
WindowPtr (long) - pointer to the window or grafix)rt; if nil, prints whole screai 
Options (integer) 

bit - if 1, shows the "Page Setup" dialog box " ^h*^"?""^ 

bit 1 - if 1 , shows the "Print" dialog box ^' 
bit 2-15 - reserved; set to sr. r' 

Print Manager erroi^ '^'^ ^^-^^ v*^»>?£^-i 

Memory Manager enors ^ iW^M ^naSBiO 



• 



0^. 





■Vr * : '. 


Hex 


Dec 


$0000 





$6201 


25089 


$6202 


25090 


$6203 


25091 


$6204 


25092 


$6205 


25093 


$6206 


25094 


$6207 


25095 


$6208 


25096 


$6209 


25097 


$620A 


25098 


$620B 


25099 


$620C 


25100 


$620D 


25101 


$620E 


25102 


$620F 


25103 


$6210 


25104 


$6211 


25105 


$62FF 


25343 



III. Appendices 
A ppendix A: DrawTools' Error Summary 



■ ( , , 



Meaning 
No error 

Too many libraries 
Sequence number out of range 
Invalid library ID 
The library is loaded 
Task signature missing/invalid 
Screen line out of range 

Task exists (or doesn't exist, depending on tool) 
SCB tasks are not aiabled 



Library buffer tables fiill (currently, mflTimiim 5 buffers, for 45K) ;t>t;>T 
Not eaiough memory in bank fw more buffers <. ^j^tobroV? 

FileType Mismatch during a HLoad/HSave niot n^O 

Sequence command mismatcfa (wrong command for this kind of pixieX'T:' 
Undefined sequence command in this vasion of DrawTools . j r? . | y^y 
Pixie exists (or doesn't exist, depaiding oa tool) . ?i f »i<f 

Playw/Device number out of range 

Game or Network Device not found ssftaAt^ ^s^M 

Not a matted pixie 

General error (c<ni^t tool descriptioD) 

- not implemented (ie. for Apple's two reserved tool numbers, #7 and #8) 



■r: -^fji ■■ 
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DPAddr 

$0-3 

4-S 

A-D 

E-F 

10-23 

24-27 

28-35 

36-41 

42-43 

4445 

46-55 

56-65 

66-75 

76-7B 

7C-7D 

7E-81 

82-83 

84-85 

86-87 

88-89 

8A-8B 

8C-FF 



Label 

SCRNPTR 

BASE_DP 

PortPlr 

GrafPCr 

MylD 

Temp 

LineTable 



StillFire 

FireMask 

PixAlloc 

PixType 

PixVsMat 

FontCode 

GrafPort* 

FcmtHeight 

LeftMargin 

RightMargin 

UtilTen^ 

CurrentLib 



A ppendix B: Direct Page Usage "^'^A 



Description 

Current drawing position, minus $2000 
Picture location in bank 

Used by DrawMain & DrawShadow, the currait grafixnl 
Ptr to QuickDraw ll's pointer to the current grafport 
Application's Memory ID, aux. type 15 

Scratchpad space for DrawTools U j^^^^ ^4^: 2 V^m 

Ptr to QuickDraw il's line table ' amtfJ^w^ ^.^e t ^ft-<.) - ^ ' ^ • ■ 

Used by fading and colour tools (don't modify) ^^t^^^ .e>:i^ ■ . - . 

Used by SCB interrupt handler (don't modify) "^"^ ^va^'^ s^S-^^i'-^ 

Bits set if fire buttons are held, %0..0O4321 

Bits tnie if fire button exists, $0..004321 -^^^ t^'^^^ ;jk?o fvi-*^^ "ji-.c - i> 
bit 7 -pixie allocated, bit 6 -pixie disabled i*-..0 «^ ^^^^'"^-^ ' 

pixie types xx^Wi^Wr^^batv a (it ^^^ii,«?(':>i ckj 

bit 7 - pixie visible, bit 6 - pixie matted ti.m^^t'^'^^ ^ . i-^^ " 

SCTatchpad space fw Animation tools >i«?^woQsiW . (*-^/4ww?-^. nA^^- 
XOR of current f<»it handle words 



Ptr to [Hiloc field in current gra^XHl 

Current font height 

Left margin 

Right margin 

Used for dereferencing 

Library ID for the current Ubrary 

Misc. or future use (dui't modify) 



1 .- 



You may use any of the scratchpad space betwe«i DrawTools calls. 
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Appendix C : DrawTools and Other Tonlsefs 

DrawTools should be con^ble with aU of the standard Apple toolsets. However, the foHowing are a few thines to 
notice. 

\, DrawTools and ESP/FTA's SoundTonis fToor : ; | 0) v^<HdJs»fJ .f .r- r 

You cannot use the SCB Interrupt tools with the Soundtrack Tools. wreiCU'wiOt j**! if^ ■ ^ 

4. Bit-manned Graphics a nd QuickDraw n - ^ . 

a) Coordinates - DrawTools' coordinate system is identical to QuickDraw's 320 mode (0...3I9, 199) However 
the coordinates are always global. Use the QuickDraw ftinction LocalToGlobal when you are asinJ 
wmdows/grafixMis to determine the proper coofdmates. 

b) 640 mode - DrawTools drawing ftmctions wUl work as you'd expect, creating 48x24 pictures instead of 24x24 
pictures. Hie coordinates are always 0...319. 0...199, even if you are using QuickDraw in 640 mode. To determine 
the propCT coordmates m a window/grafiwit, use the foUowing (in Pascal): LocalToGlobal( WindowPoint ); 
WmdowPointJi := WindowPoinLh div 2; 

DrsmwhateverAti WindowPoint.h, WindowPoint.v,picture_number ); ^^lag ' ■ " 

c) Mouse Cursor - The drawing functions and screen scrolling functioiis opaate directiy on flw screen, ignoring 
the mouse cursor. If you need a cursor on the scre«i, use HideCursor/ShowCursor. 

d) Clipping - For speed, the drawing ftmctions don't clip pictures to fit in the cUppmg regions of the currrat 
grafport (if you draw a picture, the entire picture is always drawn, even if it won't fit in a window). 

3. Memory Manage^ 

DrawTools uses auxID #15. When you shut down DrawTools, aU memory aUocated with aux ID #15 is disposed of 
(mcluding any HLoaded handles). ^^.j^i .U^.^k 
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A ppendix D: Network and Game Drivers 



. .mi Refill t;x?f^.-. -1 *} 



What are Network and Game Drivers? 7'"?>, . < . 

I>rawTools lets you assign devices for up to four players. You can specify a device number when you call 
GetFire, StillFiring or GetJoy. Device is always the GS joystick, but device 1 to 4 can be assigned to any device. 
By following the standards set in this addendum, your game (or other application) will be able to play with any 
device, allowing for even players on other GS's. All this is possible by what I call a game driver. 

A driver in GS/OS is a piece of software that runs an input/output device, like a printer or a disk drive. A game 
driver is a piece of software that DrawTools uses to run an input device, typically for a game (hence the name). 
Game drives are kept in a folder called DT.Drivers, located in the Tools folder oa a boot disk. All your 
application has to do is use SFGetFile (the standard C^... dialog) to let the players select their drivers from that 
directory. You load them with the System Loader and tell DrawTools which game driver to use for which player, and 

the rest is done automatically. 

If you want to go all the way and let pUyers play on separate GS's, youH need a net driver as well. This is a 
piece of software that DrawTools uses to communicate between separate computes, such as over a modem or an 
AppleTalk network. Using a net drivCT is a little more complicated than using game drivers alone, although 
DrawTools does a lot coordinating behind the scenes for you. You have to use a special tool called SendNetwork 
to send messages between the different GS's your program is running on. SendNetwork also returns to you status 
information about the other GS's, such as when a new player has started his computer and wants to join in, or when 
one of the existing players loses or wants to quit. Reading a pUya-'s device on another GS is done the same way as 
you would normally do, with GetJoy or the other joystick routmes. If the player is not on your GS, DrawTools asks 
the Net Driver to find out the inftmnation for you. 



Your Application 



DrawTools 



Game Driver Net Driver 



-Network - 



Your ApplicatiOT 
I 

DrawTools 



Net I>Tver Game Driver 



Apple UGS#1 
Figure 1 - How the Game and Net Drivers work together 



Apple UGS #2 



I hope that by explaining the details here, that all the people that have more time than I do will get to woric and 
start making game and net drivers. I set up the rules; somebody else makes the drivers. If you come up with a net or 
game driver, please send me a copy and a letter, and I'll try to market than with fiiture disks. If you just want to use 
the net and game drivCTs, read on to find how how to set up your programs to suj^xirt them. Located on the latest 
DrawTools' Disks is a folder called DT-Driveis, which you can copy into the Tools folder of your boot disk 
containing DrawTools. First, there is a sample game driver called Joystick that runs the GS Joystick. Second, 
there is a sample net driver called Null.NetDriver which mimics the some functions of a real net drivCT. (130 & 
131 are special commands to mimic activities on a network for testing purposes - see SendNetwork in the reference.) 
Source files for the Merlin assembler are included in the folder. You can use these to test your program if you want 
to support game drivers, or net drivers and game drivers. As I motioned previously, there is no reason "game" 
drivers have to be used in games. You might find it easier to write a game driver to operate a device like a flying 
mouse (the headset mouse used for the handicapped) than to write some kind of GS/OS driver (or whatever), and once 
written, such a driver can be used in any program suppmting game drivers. The possilMhties are enormous. , i ; 



A Few Definitions: 



DrawTools3.1 ^64. 



A device is somethiag used by a person to offer input to an application, such as a keyboard, joystick. Koala pad, or 
a microphone. 

A local device is a device connected directly to a TIGS. 

A remote device is a device connected indirectly to a IIGS, by an AppleTaUc network, or a modem, or a SCSI port to 
another IIGS. 

A Game Driver is a piece of software which operates or monitra^ a local device. 

A Net Driver is a piece of software which is used by DrawTools to communicate over a network with remote 
devices. fee .4 r<Q fc«ljtov 

What Does My Application Have To Do To Support Game Drivers? i- ?,sj^ 

What the Application does ... 

1. You will have to load the game drives desired by the play^ (using LoadEhivo") into memory. The drivers 
should be located in the DT.Drivers folder in the Tools directory of the boot disk. 

2. Use SetGameCtovCT (play^Num, DriverPtr) to iiLstall a driver for a particular pason. One driver may be shared by 
more than one person (unless, of course, it's strictly a one person device, like a joystick — it's up to the players to 
chose devices that makefen;^). j ^j^^ y-ia^i ■ ^■^ 

3. When you use GetJoy, GetFire, or StillFiring, use the playerNum to specify a particular device.^ , 

4. Unload the drivCT wIkq you are dcHie. rt , - ; . .. ■ > 

What DrawTools does ... 

DrawTools will invoke the i^ipropriate game driva instead of reading the GS joystick. If no driver exists, garbage is 
returned by the call. < .^JKvikjqA -rt- • 

i i ' 

What the Game DnvCT does ... v • ^ > . < 

The game drivCT reads the local device and returns the inff^mation requested to I>awTools, wtich hands it to your 

application. . ^-^^ . 

- ^ — i 

What Does My Application Have To Do To Use Net Drivers? ^ 

* 

What the Appligatjon does ... -?■ ;(mt-i - 

1. Load the appropriate net driver into memory. 

2. Use SetNetDriver( driverPtr ) to install the net driver. The current version of DrawTools only supports one net 
driver; you can't play ova- two different networics at the sane time. 

3. When a playo' on a local device wants to start playing, use S^dNetwork to inform the otha* GS (or GS's) that 
there is a new playo". A message is returned if the GS's are full (DrawTools only supports 4 players at a time, even 
ovCT a network). 

4. Periodically invoke SendNetwoik (eg. by placing it in your main loop) to let the net driver check on the netwwk 
and keep up-to-date with the otha- GS (or GS's). This is called polling the network. If there are new players jumping 
into the game, or old players dreeing out, SeodNetwork will r^um the ^Jix'c^ihate message. More details aa the 
uses of SendNetwoik are listed in the refa^ice. # MviYfi5S*M,it&-'''' is=:f^i«*T»vf>hH>i-; ikjurv; % 

What DrawTools Does ... . > 

If you use GetFire, GetJoy or StillFiring for a player on a remote device, DrawTools invokes tiie Net Drivo- and 

asks it to find the informati<Hi, which it returns to your application. . _^ ^ 

What the Net Driver Does ... 

The driver must handle the transmission and reception of data over the network. It takes care of identifying which 
player number on the local GS corresponds to wtiich device on which remote GS. When a new play^ enters the 
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network, the net driver finds a free player number and reports it to your af^Iication for use with GetJoy, etc. 
How to Create a Game Driver . 

1 . File descrit^ion : your driver must be stored in DT.Drivers folder in Tools folder of the boot disk. FlleType: 
Generic Load File (type $BC) AuxType I. 

2. tedff for you driver: .s.^^ ^ : - . 

BRL instruction to your driver . ,^,,.5^ ..-^/^..i-!. r.< 
Pascal string for the driva- name /^. V W ilJij' ^ = 

Your name or the name of your company ^ ^ ^ ew*"^ v^' ;n 

Driver va^ion (eg. $101 = 1.1) . 
Minimum version of DrawTools (eg. $301 = 3.1) ^ i . . 

<your driver goes here> ^ -^r^i . 

DrawTools will call your driver with a JSL to the entry point. A = command, X = player #, Y = result of the 

command. x^xT-i -^-^ 

B & D registers must (naturally) be preserved. Place the result in A. Exit with a SEC and RTL. 
The commands for game drivers are: - init driver (called by SetGameDriver, reftim error code ($6210 or other) or 
else 0) 1- GetJoy (Y=axis, called by GetJoy) 2 - GetFire (called by GetFire) 3 - StillFiring (called by StillFiring) 



Qfffiet 



Name 
Entry Pt 


Size 
(3 bytes) 


3 


Name 


(17 bytes) 


20 


CreatOT 


( 17 bytes) 


37 


VCTsion 


(wotd) 


39 


DTVersion 


(woid) 


41 


<resCTved> 


(8 bytes) 


49 







How to Create a Net Driver 



All- iii fl 



1 . File description : must be stored in DT.Drivers folder in Tools folder of the boot disk. FileType: Genmc Load File 
(type SBC) AuxType 2. 

2. Header for you driven 



Offeet 



3 

20 
37 
39 
41 
49 



EntryPt 

Name 

Creator 

Versitm 

DTVersion 

<reserved> 



Size Description 

(3 bytes) BRL instruction to your driver 

( 17 bytes) Pascal string for the driva name 

(17 bytes) Your name or the name of your conqjany 

(woid) Drive* version (eg. $100 = 1.00) 

(wad) Minimum version of DrawTools (eg $301 ==J., 

(8 bytes) Set to 

<your driver goes hero 



-isdr. - J^'"> 



DrawTools will call your driver with a JSL to the entry point. A is the coomiaiid, X = data (low), Y = data (high). 
B & D registers must be presCTved. Return with the result in A, and any data in X,Y. Exit with an RTL. 
For the commands, see the referoKe uoder SoidN^oit. You will need a pseudo game drivCT for E>rawTooIs to call 
when it wants information for a local device. For your game driver, design it to be called like a regular game driver, 
except return with a CLC (not SEC) and RTL. This will make sure DrawTools won't send the results of the 
Getloy/etc. back to you (posting local events). 
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o-fe.yot^ Appendix E : Using PicEd 3.0 ^s^.v v/tifij..: - h 

Besides the library converter utility, tiiere is a utility called PicEd that helps you to create libraries of the 
bit-mapped pictures that DrawTools' worte with. PicEd was written in TML Pascal II, v 1.1. 

When PicEd is started, there is a large grid of 24x24 black blocks to the right of the screen. Tliis is a zoom 
(fat pixels) view of the current picture. Using the mouse, you can change the blocks to differcait colours. While you 
are editing a picture, the changes you make are TEMPORARY until you select the EDIT button. This way, if you 
make a mistake, you can always revert to the original copy of the picture and start again. 

Wh^ blocks in the zoom view are changed, these changes are reflected cm a smes of pictures in the tc^lett 
comer of the screen. The large picture is a view of how the picture would look if it were drawn with the Draw48 
call. To the left of this picture are fliree smaller <Mies. The cme on the far left is drawn with Draw. The one in the 
middle is drawn with DrawOn (that is, matted) on a red background. T\ie one on the right is used when animating. 

Thore is a palette of colours to the left of the zoom view. You can change the colour you are sdcetching 
with by clicking cm a new colour. The new colour is cmtlined in black. 

Below the palette is a soies of buttons: s ■ 

QUIT - this stops PicEd. It gives no warnings, so make sure your work is saved. 

CLR - clears die zoom view to black. H u i - - . 

EDIT - savra the curroit picture in the library, and selects anofliea- for editing ^ ' 

When EDIT is first clicked, PicEd gives you three cations: (S)anie - save the current picture to library position it 
was edited from; (D)ont - don't save the current picture in the library; (N)ew - save the current picture to a new 
position. If you pick new, you will be asked for a new position (0..,31). 

LOAD - loads a library of pictures from disk. ' ' ' ' " 

SAVE - saves a library of pictures to disk. Pressing Return will use the LOAD name as the default. 
MASK - calls GenMask to create a simple matting mask. Normally, this mask is stored immediately after the 
picture it was created f<x. 

The PAL and ANI buttons are qjecial buttons which cause a new set of buttons to appear on the screen. 
The PAL (palette) buttons are: 

PAL - let's you select one of 16 palettes to use, palette being the default palette of colours used by QuickDraw. If 
you change any of the palettes (besides palette 0), the information is saved in the file PicEd.dat, and the palettes will 
be reloaded the next time you run PicGd. Some of the palettes are predefined as the 640 colours, the standard IBM 
VGA colours, metallic and rainbow colours. 

COL - change a colour in tiie current palette. ' ^. ^, 

FADE - brightens or dims a colour by using the FadeColour tool. ^"^X - 

BLND - blends two colours together to produce a third by calling the BlendCoIour tool. ;«^es«5 

The ANI (Animation) buttons as as follows: 
DONE - you are fini^ied animaticm. Gets yoa out of animadcm mode and restores the other butttms. 
SEQ - define an animaticm sequoice. If you want to animate a set of pictures in the current library, select this 
buttcm, iben type in each picture you want to animate, in ordo*. Then type 255 and type in the positicm in the 
sequence you want to lo<^ back to (ie. = first positicm, 1 - second, etc). To animate the first 3 pictures over and 
over, you'd type: then 1 then 2 then 255 then 0. 

GO! - animate the sequence you typed in. Hold down (he nxnise to stop. From left to right, the pictures are drawn: 
I) as a matted pixie on a red background, 2) as a pixie that is not matted, 3) as a 48x48 picture (by Draw48). 
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A ppendix F : Using Library Converter 1.2 

Lib. Converter, the library converter, is a utility that lets you translate a picture library template into a DrawTools 
picture library. A template is simply a super hi-resolution screen with the 32 pictures of a picture library laid out 
for you to edit with any paint program. Keep in mind that the template must be saved as a super hi-resolution 
screen and not as one of the other picture formats, such as Apple Preferred. 

Convert Template to Library ... (Command-Oo): Select this to convert a ten^late to a picture library. 
Lib.Converter will ask you which template you would like to convert. During the conversion, the template pictures 
are displayed on the desktop. Once the ten^ilate is converted, Ub.ConvertCT will ask you what name you would like 
to save the picture library as. ' ' '■ ' ' 

Display a Template ... (Command-Dd): Select this to display the pictures in a teiiq)late on the scre^. The colours 
may differ from the original template. » ---^vj -.k^ ^ 

Print a Ten^jlate ■■■ (Command-Pp): Select this to print a ten^late to the printer. Lib.Convarter uses PrintWindow 
to print the entire screai (including the pictures). . ^'''^■^■'"^-^ , 

Convert SHR Screen to SetBack ... (Command-Bb): Select this to convert a super hi-resolution screen to a packed 
super hi-resolution screen, the format used by SetBackground and SetBackground2. ^''^f**^- . ' ' ' 



be packed. 



Pack (Command-Pp): When Pack is checkmarked, the template you convCTt with '*Convat Template to Library" will 
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Appendix G : Changes Since DrawTools 3.0 

1. New ORCA/M macros. ^ rr*fv^nm ^n^i^i ^Jr-. 

to-, I 2. CLS now works with a visible cursor. - a, i^i. A vr-:;-' ^ 

^. 3. NormalRND no longer returns a uniform distribution. . . 

4. NEW WorkCiu^or2: WorkCursor that works with accelerator cards. " ^ 



5. New QDT Vectors: 



#8->WaitLine #9 -> ErasePixie ... , , . _ j . 

ftwtuw*- #10 -> Save interrupt Space #11 -> Restore mterrupt space^^^ Jl-- ^."r v-. ' ' 

7. HLoad now works with files larger than 64K. -n^tl , ^-r- 

8. Change status command for fine pixies now works. 

pj^jj. 9.Thelibrary limit has been increased to 24 fi-om 16. r, . i34£jS'«i.V" ? -^A 

10. Library Converter has been updated to version 1.1. Requires System 6.0. .^-'^^f m^r> . 

1 1. SetGameDriver no longer crashes and it returns error $62FF properly. 

12. NEW ErasePixie: A more convenient form of WipeOn. =>*>eii^<K>"j • stftAr^j- T ' , 

13. NEW EraseAllPixies. J^^. ^h^ ) l± '.- .^ 

14. NEW LoadDnver: Loads a game or net driver. 
^ 15. NEW UnloadEhiver. 

16. BaKiraph supports 16 colours for the forecolour, if you are using System 6.0. \ f^'Zl^ j.. 

17. SetNetDriver returns error $62FF properly. 

Uffi^v-^ 18.NEWSetBackground2: SetBackground with more options. .;j|e| .^^.,:.>-y, ^. 

19. NEW Keypad.Drvr & Keybrd.Drvr: game drivers for the Apple IIGS keyboard. ^ ^ 

20. NEW ResetBuffers: Clears the bank drawing buffers. 

21. NEW PrintWindow: Print the contents of a window or the screen. 

22. New self-running Micol Advanced BASIC demo. 

23. WaitLine is now more accurate: interrupts are suspended to ensure prompt response. (This was the 
problem that made Quest for the Hoard™ sluggish when many inits wwe installed.) 



Tool Index (in alphabetical order) 



Animate 40 

' V AnimatePixie 40 

BaiGiaph . 58 

BltodColour 48 

ClearPixie 39 

ClrSCBInts 50 

Cls 42 

DelSCBInt 49 

DisablePixie 40 

Draw 34 

Draw48 34 

DrawAt 34 

I>raw480n > 34 

Draw48At 34 

Draw480iiAt 35 

DrawBootlnit 30 

DrawNonnal 33 

DrawOn 34 

DrawOnAt ' 35 

DrawPage 32 

DrawPos 32 

^v-^ DrawReset 31 

DrawShadow 33 

DrawStartUp 30 

DrawStatus 31 

DrawShutDown 30 

Draw Vision 30 

&iablePixie 40 

EnableSCBInts - 49 

ErasePixie 41 

EraseAllPixies 41 

ExtendBuffers ' 32 

FadeColour 48 

FadeE>oiie 49 

FadePal ,. 46 

FindCoIour ,', ' 47 

Findftlette 48 

GetBorder ■ ■ ^ ' 44 

GenMask \- " 35 

GenAllMasks '^v 35 

GetFire ' ' ' 55 

GelJoy 55 

•r GetMHz • 58 

. J GetLibrary 37 



GetPalette 46 

GetPixie 39 

GetPixieSeq 39 

GetQDT 56 

HidePixie 40 

HLoad 58 

Home tt 5 1 

HSave^t 58 

HTab 51 

IncrFadeOut/In 43 

LoadDrivCT 53 

LoadLibrary 37 

NewPixie 38 

NormalRND 57 

Odds ,^ 57 

Print 52 

PrintHex 52 

Printint 52 

PrintWindow 59 

QuickFadeOut/In 42 

QuickWipe 42 

Ready2Print 51 

ResetBuffers . 32 

ResetSCBs 44 

ResumeSCBInts 50 

RND 57 

ScrolILinesL 45 

ScroULuiesR 45 

ScrolllinesU 45 

ScrolILinesD 45 

SaidNetworic 53 

Se^Backgroimd 36 

SetBackgrouiKl2 36 

SetBorder 44 

SetColour 47 

SetColPercent 47 

SetDrawI^ge 33 

SetDrawPos 32 

SetGameDrivCT 53 

SetLibrary • 37 

SetLTMargins 51 

SetNetDriver 53 
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SetPalerte 

SetPixie 

SetPixieSeq 

SetSCBInt 

SetSCBs 

ShowPixie 

ShadowOtf 

ShadowOn 

StillFiring 

StiliWorking 

UnfedePal 

UnJoadDrivCT 

UnloadLibrary 

VBWipe 
VTab 

c 

WaitVB 

WaitLine 

WipeOn 

WorkCursor 

WorkCursor2 
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